Skip to content
ivanklee86Public

About

πŸ—οΈπŸ—οΈπŸ—οΈ A CLI for Platform-izing devcontainers

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

gantry

CI Coverage Test Execution Time

A CLI for Platform-izing devcontainers in microservices, widely distributed, or just complicatedβ„’ situations.

Why gantry?

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.json configuration 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.json on demand.

Installing gantry

With go

go install github.com/ivanklee86/gantry@latest

With Homebrew

brew install ivanklee86/tap/gantry

With Docker

docker pull ghcr.io/ivanklee86/gantry:latest
docker run --rm ghcr.io/ivanklee86/gantry:latest

To embed gantry in your own Dockerfile:

COPY --from=ghcr.io/ivanklee86/gantry:latest /usr/local/bin/gantry /usr/local/bin/gantry

Usage and Configuration

Quick start (CLI flags)

Build 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.json

Write 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.json

YAML configuration file

For 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.jsonnet

Run it:

gantry build --config gantry.yaml --write

CLI flags --output-path and --write override the values in the config file when specified.

Multi-layer example

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.jsonnet
gantry build --config gantry.yaml --write

Authentication

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}

About

πŸ—οΈπŸ—οΈπŸ—οΈ A CLI for Platform-izing devcontainers

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages