A CLI for Platform-izing devcontainers in microservices, widely distributed, or just complicatedβ’ situations.
Devcontainers are an amazing tool for building shared, secure development environments for distributed teams. However, managing the configuration (Dockerfile, devcontainer.json) comes with its own complexities: teams want to customize tools, programming languages have different standards, and services proliferate.
There are well-known solutions for Dockerfiles like using base images and docker bake.
But what if you're a development team that wants a standard VSCode configuration for the astral stack? Or a Platform Engineering team standardizing your AI coding tool stack?
gantry is a light-weight CLI that solves this problem by:
- Allowing teams to store
devcontainer.jsonconfiguration in git repositories. - Uses jsonnet to merge standard configurations (e.g. a base Python
devcontainer.json) with use-case (e.g. a Jupyter plugin for data teams) and/or team (e.g. Svelte for a fullstack team) from remote repositories. - Let developers define a configuration as a YAML file on disk and re-generate the
devcontainer.jsonon demand.
go install github.com/ivanklee86/gantry@latestbrew install ivanklee86/tap/gantrydocker pull ghcr.io/ivanklee86/gantry:latest
docker run --rm ghcr.io/ivanklee86/gantry:latestTo embed gantry in your own Dockerfile:
COPY --from=ghcr.io/ivanklee86/gantry:latest /usr/local/bin/gantry /usr/local/bin/gantryBuild from a single remote repository and print to stdout:
gantry build --repo https://github.com/ivanklee86/devcontainers --ref main --files devcontainer_configs/bases/go/devcontainer.jsonWrite the result to a file:
gantry build --repo https://github.com/ivanklee86/devcontainers --ref main \
--files devcontainer_configs/bases/go/devcontainer.json \
--write --output-path .devcontainer/devcontainer.jsonFor multi-repository merges or to keep the configuration in source control, use a YAML file:
version: 1
output_path: .devcontainer/devcontainer.json
overlays:
- repo: https://github.com/ivanklee86/devcontainers
ref: main
files:
- devcontainer_configs/bases/go/devcontainer.json
- repo: https://github.com/org/team-overlays
ref: refs/heads/main
subdirectory: data-team
files:
- jupyter.jsonnetRun it:
gantry build --config gantry.yaml --writeCLI flags --output-path and --write override the values in the config file when specified.
A typical setup has three layers: a shared org base, a language overlay, and a team overlay. Each layer is a Jsonnet file that merges on top of the previous result.
Layer 1 β org base (devcontainers/bases/base.json, plain JSON):
{
"name": "base",
"image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
"remoteUser": "vscode",
"customizations": {
"vscode": {
"settings": {
"editor.formatOnSave": true,
"editor.rulers": [100]
},
"extensions": ["GitHub.vscode-github-actions", "redhat.vscode-yaml"]
}
},
"postCreateCommand": {
"upgrade": "sudo apt-get update && sudo apt-get upgrade -y"
}
}Layer 2 β language overlay (devcontainers/languages/python.jsonnet):
Uses +: to deep-merge into the base rather than replacing it.
{
name: "python",
image: "mcr.microsoft.com/devcontainers/python:3.13",
customizations+: {
vscode+: {
settings+: {
"python.defaultInterpreterPath": "/usr/local/bin/python",
"[python]": { "editor.defaultFormatter": "charliermarsh.ruff" },
},
extensions+: [
"charliermarsh.ruff",
"ms-python.python",
"ms-python.mypy-type-checker",
],
},
},
postCreateCommand+: {
"install-uv": "curl -LsSf https://astral.sh/uv/install.sh | sh",
},
}Layer 3 β team overlay (team-overlays/data-team/jupyter.jsonnet):
{
name: "data-team-python",
customizations+: {
vscode+: {
extensions+: [
"ms-toolsai.jupyter",
"ms-toolsai.vscode-jupyter-cell-tags",
],
},
},
remoteEnv: {
TEAM: "data",
JUPYTER_PORT: "8888",
},
forwardPorts: [8888],
postCreateCommand+: {
"install-deps": "uv sync --all-extras",
},
}gantry.yaml wiring all three together:
version: 1
output_path: .devcontainer/devcontainer.json
overlays:
- repo: https://github.com/org/devcontainers
ref: refs/heads/main
subdirectory: bases
files:
- base.json
- repo: https://github.com/org/devcontainers
ref: refs/heads/main
subdirectory: languages
files:
- python.jsonnet
- repo: https://github.com/org/team-overlays
ref: refs/heads/main
subdirectory: data-team
files:
- jupyter.jsonnetgantry build --config gantry.yaml --write| Method | Flags |
|---|---|
| Token (HTTPS) | --token |
| Basic auth | --username / --password |
| SSH key | --ssh-key-path / --ssh-key-password |
In YAML configs, all string fields support ${ENV_VAR} interpolation:
overlays:
- repo: https://github.com/org/private-devcontainers
ref: refs/heads/main
files:
- base.jsonnet
auth:
token: ${GITHUB_TOKEN}