Forgeplane Docker Compose validation

Use Docker Compose to validate the packaged local stack. The default path checks the coordinator, database initialization, dependencies, and control-plane access; the opt-in OpenTofu profile proves a real queue-to-worker run. Use the Helm chart for a durable Kubernetes installation.

Validate the control plane

Run the packaged validation path:

make docker-build
make docker-up
make deploy-test

make docker-build creates local release-style binaries and images. make docker-up generates local TLS material and starts PostgreSQL, NATS, the coordinator, and the default worker. make deploy-test checks coordinator health, readiness, and authenticated API access.

This path does not prove an IaC run. The default/production worker image bundles no Terraform, OpenTofu, or Ansible binaries and advertises [].

Run the opt-in OpenTofu profile

The repository provides a separate Compose worker for real tool execution:

make docker-up-opentofu

That profile builds Dockerfile.worker-opentofu, verifies and installs OpenTofu 1.10.6, and advertises only the canonical tofu capability. It does not modify the default worker image or production Helm configuration.

For a bounded, self-cleaning acceptance test, run:

make quickstart-smoke

The smoke path builds the opt-in tool worker, serves the committed provider-free fixture over local TLS, queues a plan through the public registry API, waits up to two minutes for success, verifies a 0 add / 0 change / 0 destroy result, and removes its containers, volumes, and generated fixture data.

Run the opt-in Ansible profile

To validate Ansible playbook execution with Compose, run the dedicated Ansible worker profile:

docker compose \
  -f docker-compose.yml \
  -f docker-compose.ansible.yml \
  --profile ansible \
  up -d --build worker-ansible

This builds Dockerfile.worker-ansible with its pinned Python base image and ansible-core 2.20.8, advertising the ansible capability.

Understand the image contract

Image	Role	Bundled IaC capabilities
Coordinator	HTTP API, UI, scheduler, persistence, drift, and worker control plane	Not applicable; it does not execute IaC
Default worker	Execution runtime and built-in executor code	None; advertises []
Local OpenTofu worker	Opt-in execution image for repository validation	OpenTofu 1.10.6; advertises only tofu
Local Ansible worker	Opt-in execution image for playbook validation	ansible-core 2.20.8 and OpenSSH; advertises ansible
Migrator	Initializes the database schema	None

Every tool-enabled image must bundle and verify the binary, then advertise only the capabilities that image can execute. Pin images by immutable release or digest outside local development.

Keep execution isolated

The coordinator is the control plane. Workers execute module code and provider processes. Keep their identities and writable filesystems separate.

The local worker container starts a root supervisor with a tightly limited capability set: CHOWN, DAC_OVERRIDE, FOWNER, SETUID, and SETGID. The supervisor uses those capabilities to hand workspace ownership to the configured isolated IaC UID/GID and to materialize or clean private run files. Tool processes, including ansible-playbook, run as that isolated identity rather than as root. no-new-privileges remains enabled, and worker-only writable mounts are constrained to temporary files and isolated workspaces. Do not mount those paths or provider credentials into the coordinator.

Compose credentials, certificates, and storage are local test material. They are not a production secret-management or backup design.

Compose publishes every port on 127.0.0.1 only, and the coordinator requires a worker client certificate on gRPC. Do not expose the stack beyond the host.