Run the local stack | Beacon containers

Step 01 of 06

Learn the concept

One container is packaging. A stack is behaviour. Compose gives Beacon a local network name, a durable SQLite volume, a health check, and a repeatable command a teammate can run without reading your shell history. It is development infrastructure, not production orchestration wearing a fake moustache.

Compose gives the local stack names and lifetimes. The service can be recreated while the named volume survives, and other services would reach it as `http://beacon:7427` on the project network.

Step 01

The ideas this is made of

A service name becomes local DNS

Compose creates a network for the project unless you say otherwise. Each service joins it and receives DNS for its service name. If a later UI service needs Beacon, it should call http://beacon:7427, not localhost. Inside a container, localhost means the same container. That tiny fact has consumed heroic debugging hours.

Named volumes outlive containers

A container's writable layer is deleted with the container. A named volume is managed separately by Docker and can be mounted into new containers. Beacon's SQLite database belongs there for local development. The volume is still on one machine, so this is durability for laptops, not a backup strategy.

Health checks turn start into readiness evidence

A container can be running while the service inside is still opening its database. Compose health checks run a command inside the container and record starting, healthy, or unhealthy. Distroless has no shell, curl, or wget, so use a Beacon healthcheck mode or copy a tiny probe binary on purpose.

Environment belongs at the boundary

Compose can set explicit environment values and load an env_file. That is good for local configuration such as BEACON_DB_PATH=/var/lib/beacon/beacon.db. Do not bake environment-specific values into the image. The same image should run on a laptop, in CI, and later in a cluster with different runtime config.

A minimal service with a health check

services:
  web:
    image: nginx:1.27-alpine
    ports:
      - "8080:80"
    healthcheck:
      test: ["CMD", "wget", "-q", "-O", "-", "http://localhost/"]
      interval: 10s
      timeout: 2s
      retries: 3

There is no obsolete top-level version: key. Compose v2 reads the service map directly and applies the current Compose Specification.

Compose and production orchestration

Concern	Compose	Kubernetes later
Target	One developer machine	Cluster of machines
State	Named local volumes	PersistentVolumeClaims
Readiness	Healthcheck status	Readiness probe
Scaling	Manual replicas	Controller reconciliation
Use	Development stack	Production platform

What these are called on the job

Service — A Compose-defined container role with image, ports, environment, and runtime settings.
Named volume — Docker-managed persistent storage referenced by name in the Compose file.
Healthcheck — A command run by the runtime to classify a container as starting, healthy, or unhealthy.