Skip to main content

Using Geodesic with Atmos Devcontainers

Note: atmos devcontainer requires minimum Atmos version v1.200.0

This guide explains how to use Geodesic with atmos devcontainer commands.

Overview​

Geodesic is a robust Linux toolbox container, crafted to optimize DevOps workflows. It comes pre-loaded with essential DevOps tools and dependencies, providing a consistent development environment without requiring software installation on individual workstations.

Dev Containers (Development Containers) are a standardized way to define and run development environments inside containers. They provide consistent, reproducible environments with all necessary tools and dependencies pre-configured.

With atmos devcontainer commands, you can run Geodesic as a dev container with:

  • Native Docker/Podman integration
  • Configuration in atmos.yaml
  • Standard dev container specification support
  • Consistent CLI experience across all Atmos commands

Learn more in the Devcontainer Documentation.

Setup Steps​

1. Add Devcontainer Configuration to atmos.yaml​

Add a top-level devcontainer section to your atmos.yaml:

devcontainer:
  geodesic:
    spec: !include devcontainer.json

2. Create devcontainer.json​

Create a devcontainer.json file in your repository root (same directory as atmos.yaml) with your Geodesic configuration:

{
  "name": "Geodesic",
  "image": "cloudposse/geodesic:latest",
  "workspaceFolder": "/workspace",
  "workspaceMount": "type=bind,source=${localWorkspaceFolder},target=/workspace",
  "mounts": [
    "type=bind,source=${localEnv:HOME}/.config,target=/root/.config",
    "type=bind,source=${localEnv:HOME}/.aws,target=/root/.aws",
    "type=bind,source=${localEnv:HOME}/.ssh,target=/root/.ssh,readonly",
    "type=bind,source=${localEnv:HOME}/.kube,target=/root/.kube",
    "type=bind,source=${localEnv:HOME}/.terraform.d,target=/root/.terraform.d"
  ],
  "containerEnv": {
    "ATMOS_BASE_PATH": "/workspace",
    "ATMOS_XDG_CONFIG_HOME": "/root/.config",
    "ATMOS_XDG_DATA_HOME": "/root/.local/share",
    "ATMOS_XDG_CACHE_HOME": "/root/.cache",
    "TERM": "${localEnv:TERM}"
  },
  "remoteUser": "root",
  "runArgs": [
    "--hostname=geodesic"
  ]
}

3. Use Geodesic Commands​

Common commands for working with Geodesic:

CommandDescription
atmos devcontainer shell geodesicStart interactive shell in Geodesic
atmos devcontainer start geodesicStart Geodesic container (without attaching)
atmos devcontainer attach geodesicAttach to running Geodesic container
atmos devcontainer stop geodesicStop Geodesic container
atmos devcontainer exec geodesic -- <cmd>Execute command in running container

4. (Optional) Add Shell Alias​

For convenience, add a shell alias to your atmos.yaml:

aliases:
  shell: "devcontainer shell geodesic"

Now you can use:

atmos shell  # Equivalent to: atmos devcontainer shell geodesic

Configuration Reference​

Basic Configuration​

devcontainer:
  geodesic:
    spec:
      image: "cloudposse/geodesic:latest"
      workspaceFolder: "/workspace"

Advanced Configuration​

devcontainer:
  geodesic:
    settings:
      runtime: podman  # Optional: docker, podman, or omit for auto-detect
    spec:
      image: "cloudposse/geodesic:latest"
      workspaceFolder: "/workspace"
      workspaceMount: "type=bind,source=${localWorkspaceFolder},target=/workspace"
      containerEnv:
        ATMOS_BASE_PATH: "/workspace"
        ATMOS_IDENTITY: "acme-identity"  # For atmos auth integration
      remoteUser: "root"
      runArgs:
        - "--hostname=geodesic"

Integration with Atmos Auth​

If you're using atmos auth, ensure your devcontainer mounts the credentials:

{
  "mounts": [
    "type=bind,source=${localEnv:HOME}/.config/atmos,target=/root/.config/atmos,readonly"
  ],
  "containerEnv": {
    "ATMOS_IDENTITY": "acme-identity"
  }
}

See Configuring Geodesic with Atmos Auth for complete authentication setup.

Troubleshooting​

Issue: "Command not found: atmos devcontainer"​

Solution: Upgrade to Atmos v1.200.0 or later:

atmos version  # Check current version

Issue: Container doesn't start​

Solution: Verify your configuration with:

atmos validate devcontainer

Issue: Workspace not mounted​

Cause: Incorrect workspaceMount configuration.

Solution: Ensure the mount uses your actual repository path:

{
  "workspaceMount": "type=bind,source=${localWorkspaceFolder},target=/workspace"
}

Next Steps​