Getting Started¶

This tutorial walks through setting up the macOS host and opening the dev container for the first time (to develop the container itself). If you want to use the pre-built image in another project, see Using the Container in Projects.

Prerequisites¶

1. Docker runtime via Colima¶

brew install colima docker
colima start --vm-type=vz --ssh-agent --cpu 8 --memory 8 --disk 60

The --ssh-agent flag forwards your macOS SSH agent into the Lima VM. To make these settings permanent, ensure ~/.colima/default/colima.yaml persists not just sshAgent but also the VM type and resource allocation — otherwise a colima restart reverts to the defaults:

vmType: vz
cpu: 8
memory: 8
disk: 60
sshAgent: true

2. 1Password desktop app¶

Open 1Password → Settings → Developer
Enable "Use the SSH agent"
Ensure your SSH keys are stored in 1Password

3. Point `SSH_AUTH_SOCK` at the 1Password agent¶

Add to ~/.zshrc:

export SSH_AUTH_SOCK="$HOME/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"

Colima's --ssh-agent forwards whatever SSH_AUTH_SOCK points to into the VM. By default macOS sets it to the system ssh-agent (which has no keys). Pointing it at the 1Password socket ensures the container sees your keys.

Also add IdentityAgent to ~/.ssh/config for direct SSH on the host:

Host *
  IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"

4. VS Code¶

Install VS Code with the Dev Containers extension.

5. Per-project environment variables¶

Each project uses its own source file so that multiple projects on the same host do not collide. See Per-Project Variable Isolation below.

Per-project variable isolation¶

Each project that uses this container needs its own environment variables on the host. Since multiple projects may be open on the same machine simultaneously, all variables use a per-project prefix (e.g. MY_PROJECT_).

Copy examples/env.sh to your project's .devcontainer/env.sh and fill in the 1Password op:// paths for your secrets:

cp examples/env.sh .devcontainer/env.sh

The copied template ships the platform token/URL exports (and GIT_SIGNING_KEY) commented out — uncomment the block for your GIT_PLATFORM (e.g. MY_PROJECT_GITHUB_TOKEN) before your first open. GIT_USER_NAME, GIT_USER_EMAIL, and GIT_PLATFORM are already active.

Before opening the devcontainer in VS Code, source the file:

source .devcontainer/env.sh
# Prints (example, for a repo named my-infra): [env] Project prefix: MY_INFRA
code .

The prefix is derived automatically from the git repository name — hyphens and dots become underscores and the result is uppercased. For example, a repo named my-infra produces MY_INFRA_GITHUB_TOKEN, MY_INFRA_GIT_PLATFORM, etc.

Copy the printed prefix into devcontainer.json wherever you see MY_PROJECT_ (${localEnv:...} names must be static strings and cannot be computed at devcontainer startup time). The .devcontainer/env.sh file is safe to commit and is tracked in git — it contains only 1Password op:// references, never raw secret values. Secrets are resolved from 1Password by op read when you source the file and are never written into it.

Quick start (developing the container)¶

git clone git@github.com:felipecoelho90/dev-container.git
cd dev-container
source .devcontainer/env.sh   # prints the prefix; set variables
code .

When prompted by VS Code, click "Reopen in Container". The first build takes ~10–15 minutes due to Python and Ruby compilation; subsequent opens use the cached image.

Verify the setup¶

Inside the container:

# SSH agent: lists your 1Password keys
ssh-add -l

# No private key files on disk
ls ~/.ssh/
# Expected: config  known_hosts  (nothing else)

# Monitor reachable
curl -s http://localhost:9090/api/state | jq .updated_at

Build and test locally¶

make build       # build dev-container:latest
make test        # run BATS unit tests
make test-init   # test entrypoint setup/start scripts
make test-smoke  # quick version-string smoke test