Many Tiltfiles and Many Repos
Most of our example projects use a single Tiltfile. All the source files, Dockerfiles, and Kubernetes configs are in a single folder.
But your project may be organized differently!
How to Organize Your Project for Tilt
Tilt does not require a particular project structure. We try to provide APIs to help you pull the services you need into your dev environment, no matter where they’re defined.
Do NOT restructure your project for Tilt. Instead, restructure your Tiltfiles to match your project structure!
We’ve seen many patterns, including:
One main Tiltfile that subincludes a subdirectory Tiltfile for each service.
Individual service Tiltfiles that include a library of common functions.
Conditional loading of sets of services based on what you have checked out.
Loading some services for editing and some services for running read-only.
Loading prebuilt services from other repos.
Checking out git repos or git submodules from the Tiltfile.
In this doc, we’ll take a tour of the APIs that make these patterns possible.
Loading Library Functions
Suppose you have two services that share dev conventions. Maybe you run them together sometimes! Or maybe you don’t. But you want to factor out common logic for setting up their dev environment.
This is where
load() can help. You can use it to load
shared constants or functions from a relative path:
load('../common/Tiltfile', 'VERSION', 'common_config_yaml') print('Loading version: ', VERSION) k8s_yaml(common_config_yaml())
Another pattern is where two services have independent Tiltfiles. But sometimes you want to load them together!
include() function loads files that don’t export
any helper functions.
Loading Services Conditionally
We have an example project with an auth service. Sometimes we want to run it with fake user data. Sometimes we want to run it with real Github OAuth login. Sometimes we want to run it with HTTPS instead of HTTP.
load_dynamic() function doesn’t have the nice
syntax for loading constants, but does give you the flexibility to conditionally
os.path.exists to see if you have OAuth client secrets or localhost
HTTPS certificates. If you do, it uses the real Github OAuth login
server. Otherwise, it uses fake user data.
USE_OAUTH2 = os.path.exists('../.secrets/values-dev.yaml') USE_TLS = False if USE_OAUTH2: symbols = load_dynamic('../oauth2-proxy/Tiltfile') USE_TLS = symbols['USE_TLS']
Configuring to-run vs to-edit Services
As you have more services, you may need to run subsets of them.
One way to handle this is to have a Tiltfile for each common configuration.
Other teams load all the services in a single Tiltfile, then add controls to enable/disable sets of them.
Tilt has some built-in support for this!
tilt enable a b: enable service ‘a’ and ‘b’
tilt enable --only a b: enable ‘a’ and ‘b’, and disables all others
tilt enable --all: enable all services
tilt disable a b: disable ‘a’ and ‘b’
tilt disable --all: disable all services
For more complicated configurations, you can define your own flags to
to specify sets of services to run or to edit. For more examples, see the
per-user config guide.
Managing other git Repositories
The simplest way to handle multi-repository projects is to ask the user to check out other repos as a sibling directory.
if not os.path.exists('../backend'): fail('Please "git clone" the backend repo in ../backend!') include('../backend/Tiltfile')
You can also supply the repository as an environment variable.
backend_dir = os.environ.get('BACKEND_REPO_DIR', '../backend') if not os.path.exists(backend_dir): fail('Please "git clone" the backend repo in %s!' % backend_dir) include(os.path.join(backend_dir, 'Tiltfile'))
Many sophisticated projects use this approach, including the ClusterAPI project for loading servers for each host they deploy to!
Other teams in the Tilt community handle multi-repo projects directly from their
git_resource extension has functions for checking out arbitrary
repos and deploying the resources they contain.
load('ext://git_resource', 'git_checkout') git_checkout('email@example.com:tilt-dev/tilt-example-html.git#master', '/path/to/local/checkout')
Go to the
for more details.
Managing Extension Repositories
Finally, Tilt has a set of community-contributed extensions in the
The community extensions contain both common functions to define your dev environment, and common servers you may want to use.
Many teams manage their own extension repos for extensions that are specific to their orgs! You can read more about how to use them in the Extensions Guide.