Toolchain container

This directory is a toolchain container setup: Terraform runs in an ephemeral Docker container, while the actual project (.tf files, state, etc.) lives in a sibling directory on the host and is bind-mounted in.

hashicorp-terraform/
├── terraform-in-docker/          ← Compose, Dockerfile, .env (the runner)
└── insecure-user-with-docker/    ← Terraform project (mounted into the container)

The container provides the toolchain (Terraform version, shell, SSH keys). It is not a long-running service beside the project — each command is a one-off docker compose run.

Configuration

The project name and the Terraform working directory are driven by COMPOSE_PROJECT_NAME. The default value lives in .env:

COMPOSE_PROJECT_NAME=insecure-user-with-docker

Compose uses the effective project name for:

• the Docker Compose project name
• the bind mount: ../${COMPOSE_PROJECT_NAME} on the host is mounted to /root/${COMPOSE_PROJECT_NAME} in the container

You can also set the project name at runtime. Precedence (highest to lowest):

1. -p / --project-name on the command line
2. COMPOSE_PROJECT_NAME in the shell environment
3. COMPOSE_PROJECT_NAME in .env
4. the name: field in compose.yaml (here: ${COMPOSE_PROJECT_NAME})

A shell environment variable overrides the value from .env. Because the bind mount uses ${COMPOSE_PROJECT_NAME} as well, an override changes both the Compose project name and the mounted directory — the sibling folder must exist.

Examples:

# override for a single command
COMPOSE_PROJECT_NAME=other-project docker compose run --rm terraform terraform plan

# same, via flag
docker compose -p other-project run --rm terraform terraform plan

To switch projects permanently, change COMPOSE_PROJECT_NAME in .env to match the sibling folder name under the repo root.

Usage

Build the image

docker compose build

Run terraform

docker compose run --rm terraform terraform version

Create resources

docker compose run --rm terraform terraform init
docker compose run --rm terraform terraform apply
docker compose run --rm terraform terraform destroy

Interactive shell in the mounted terraform dir

docker compose run --rm terraform fish # or ash