Docker Compose¶

deploy/docker-compose.yml runs the dashboard on your machine with a hardened container: read-only root file system, no capabilities, no privilege escalation, and the port bound to the loopback address. The compose file is the source of truth; this page explains it.

docker compose -f deploy/docker-compose.yml up --build

Run it from the repository root. It builds the image from deploy/Dockerfile (tagged vpcatlas:0.1.0 locally) and opens http://127.0.0.1:8080. To use the published image instead, replace the build: block with image: vpcatlas/vpcatlas:0.1.0.

What each part does¶

Setting	Effect
`ports: "127.0.0.1:${VPCATLAS_PORT:-8080}:8080"`	Reachable only from your machine. Change `VPCATLAS_PORT` to use another host port.
`user: "${LOCAL_UID:-10001}:${LOCAL_GID:-10001}"`	Runs as the image user by default. On Linux export `LOCAL_UID=$(id -u) LOCAL_GID=$(id -g)` first so the container can read your `~/.aws`.
`environment: HOME=/home/atlas`	Keeps the home directory (and so the location of `.aws`) fixed when the user id is not the image's.
`VPCATLAS_REFRESH_SECONDS=${VPCATLAS_REFRESH_SECONDS:-900}`	Rescans every 15 minutes unless you set it.
`VPCATLAS_REGIONS`, `VPCATLAS_PROFILE`, `VPCATLAS_ROLE_ARN`, `VPCATLAS_EXTERNAL_ID`, `VPCATLAS_SESSION_DURATION`, `VPCATLAS_ROLE_SESSION_NAME`, `VPCATLAS_EXCLUDE_REGIONS`, `VPCATLAS_AUTH_USER`, `VPCATLAS_AUTH_PASSWORD`	Passed through from your shell only when set there. See the dashboard page.
`AWS_PROFILE`, `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`	The standard credential variables, passed through when set in your shell.
`volumes: ${HOME}/.aws -> /home/atlas/.aws (read-only)`	Your shared credentials and config files. Compose refuses to start if the directory does not exist (`create_host_path: false`).
`read_only: true` and `tmpfs: /tmp`	Nothing in the image can be modified; only `/tmp` is writable, in memory.
`cap_drop: ALL`, `no-new-privileges:true`	No Linux capabilities and no way to gain them.
`restart: unless-stopped`	Comes back after a reboot or a crash.

A variable that is left unset on the host is not passed to the container.

Credentials¶

Pick one:

A named profile. Keep the ~/.aws mount and run AWS_PROFILE=audit docker compose -f deploy/docker-compose.yml up. A credential_process profile needs its helper, which the container does not have; an SSO profile works from the mounted cache while its token is valid.
Environment variables. For an SSO profile or any short-lived session, export the keys and start Compose; the file passes AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN through without writing them anywhere:

eval "$(aws configure export-credentials --profile my-audit --format env)"
docker compose -f deploy/docker-compose.yml up

If you have no ~/.aws directory, delete the volumes block, or Compose will not start. - A role in another account. Add VPCATLAS_ROLE_ARN (and VPCATLAS_EXTERNAL_ID when the trust policy has one) to your shell before up. See iam.md.

Persisting the history¶

By default the history lives in the memory of the container and disappears on docker compose down. To keep it, add a writable volume and point VPCATLAS_SNAPSHOT_URI at it. For example, in the service:

    environment:
      - VPCATLAS_SNAPSHOT_URI=file:///data
    volumes:
      - vpcatlas-data:/data

and, at the top level of the file, volumes: { vpcatlas-data: {} }. A new named volume is owned by root, so with the default user create the directory with the right owner once, or point VPCATLAS_SNAPSHOT_URI at an s3:// location the credentials can write to. This addition is not in the shipped file.

Protecting it¶

The port is bound to the loopback address, so only your machine reaches it. If you publish it further, set VPCATLAS_AUTH_PASSWORD in your shell before up (the user name is atlas, or VPCATLAS_AUTH_USER) and put HTTPS in front of it.