Course outline

01 · Phase 1 — Project Foundation16/16

02 · Phase 2 — Organization Service20/20

03 · Phase 3 — User Service10/10

04 · Phase 4 — Authentication Service10/10

05 · Phase 5 — API Gateway9/9

06 · Phase 6 — Flat Service6/6

07 · Phase 7 — Resident Service7/7

08 · Phase 8 — Maintenance Service7/7

09 · Phase 9 — Payment Service7/7

10 · Phase 10 — Complaint Service7/7

11 · Phase 11 — Notice Service7/7

12 · Phase 12 — Visitor Service6/6

13 · Phase 13 — Staff Service6/6

14 · Phase 14 — Notification Service7/7

15 · Phase 15 — Redis Integration6/6

16 · Phase 16 — Kafka Integration8/8

17 · Phase 17 — Observability7/7

18 · Phase 18 — Performance Engineering6/6

19 · Phase 19 — Production Deployment11/11

20 · Phase 20 — Production Readiness8/8

Stage 7 · Master

Phase 19 — Production Deployment

Docker Compose

Wire organization's api and migrate images into docker-compose.yml with real health checks, a migrate-then-serve start order, and pinned digests so a local stack behaves like the deployment pipeline that will eventually replace it.

14 min readHOA Backend Engineering CourseMaster

A Local Stack That Diverges From Production Teaches the Wrong Lessons

docker-compose.yml has run PostgreSQL and Redis since Part 1, but organization itself has always run as a host process during development, started by air for hot reload. Lesson 1 built real images; this lesson wires them into Compose so the local stack exercises the same migrate-then-serve ordering, health checks, and non-root, read-only container constraints Kubernetes will enforce in Lesson 3 — catching a container-only bug on a laptop instead of in staging.

Terminal — repository root

$touch compose.override.local.yaml

// Compose's file merge semantics let a small override file add the organization service without duplicating postgres/redis definitions already in docker-compose.yml.

Create docker-compose.yml before adding the code

$touch docker-compose.yml

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

docker-compose.yml — organization-migrate, organization, and organization-healthcheck additions

services:
  organization-migrate:
    build:
      context: .
      dockerfile: services/organization/Dockerfile
      target: migrate
    image: ghcr.io/hoa-platform/organization-migrate:local
    command: ["-path", "/app/migrations", "-database", "${MIGRATE_DATABASE_URL}", "up"]
    depends_on:
      postgres:
        condition: service_healthy
    restart: "no" # a one-shot job must never restart itself into a crash loop

  organization:
    build:
      context: .
      dockerfile: services/organization/Dockerfile
      target: api
    image: ghcr.io/hoa-platform/organization-api:local
    read_only: true
    user: "65532:65532"
    environment:
      DATABASE_URL: ${DATABASE_URL}
      REDIS_ADDRESS: redis:6379
      ORGANIZATION_HTTP_ADDR: :8081
    ports:
      - "8081:8081"
      - "9090:9090" # internal listener: healthz, readyz, metrics
    depends_on:
      organization-migrate:
        condition: service_completed_successfully
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "/app/organization-api", "-healthcheck"] # a distroless image has no curl or wget to shell out to
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 5s

  organization-healthcheck:
    image: curlimages/curl:8.11.1
    depends_on:
      organization:
        condition: service_healthy
    command: ["curl", "-sf", "http://organization:9090/healthz"]
    profiles: ["verify"] # disposable — only runs when explicitly requested, never as part of a normal 'up'

service_completed_successfully on organization-migrate is what enforces migrate-then-serve ordering — organization will not even attempt to start until the migration container has exited with status 0, and depends_on's default condition (service_started) would not have provided that guarantee.

MIGRATE_DATABASE_URL is a second .env value, not a typo of DATABASE_URL

DATABASE_URL stays a postgres://-scheme string for pgxpool.New in the api service, exactly as everywhere else in this course. Compose's ${VAR} interpolation happens once, at compose-parse time on the host, and — unlike a POSIX shell — it has no syntax for stripping a prefix off a variable's value. So the developer's .env defines a second value, MIGRATE_DATABASE_URL, already written with the pgx5:// scheme golang-migrate's driver requires, and only organization-migrate's command: array references it.

A distroless image has no shell for a traditional HEALTHCHECK

gcr.io/distroless/static-debian12 ships no shell, curl, or wget — a CMD-form healthcheck like curl -f localhost/healthz would fail immediately with 'exec format error' or 'not found'. The binary itself needs a small internal -healthcheck flag (added to cmd/api's main.go below) that performs the same HTTP check in-process and exits 0 or 1, which Docker's healthcheck mechanism can invoke without a shell.

Create services/organization/cmd/api/main.go before adding the code

$mkdir -p services/organization/cmd/api && touch services/organization/cmd/api/main.go

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/organization/cmd/api/main.go — healthcheck flag addition

func main() {
	healthcheckMode := flag.Bool("healthcheck", false, "perform an in-process liveness check and exit")
	flag.Parse()

	if *healthcheckMode {
		resp, err := http.Get("http://localhost:9090/healthz")
		if err != nil || resp.StatusCode != http.StatusOK {
			os.Exit(1)
		}
		os.Exit(0)
	}

	// ... normal server startup continues below
}

The flag dials 9090, not the API port. Observability moved healthz, readyz and metrics onto a separate internal listener, so a healthcheck aimed at 8081 would now get a 404 from the public router and report a healthy container as failing. Reusing the exact route Kubernetes' own probe will use in Lesson 3 is what keeps the two from drifting apart.

Pin Every Image Compose Does Not Build From This Repository

postgres, redis, and the disposable curl healthcheck sidecar are not built from this Dockerfile — they are pulled. Part 1's docker-compose.yml already pins PostgreSQL and Redis by tag; this lesson tightens that to digests for the images this lesson introduces, since a tag like curlimages/curl:8.11.1 can still be repointed by its publisher even though it looks specific.

Terminal — repository root

$docker buildx imagetools inspect curlimages/curl:8.11.1 --format '{{json .Manifest.Digest}}'

// Resolves today's real digest — run this yourself rather than trusting a value printed in a lesson written on a different day.

Create docker-compose.yml before adding the code

$touch docker-compose.yml

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

docker-compose.yml — digest-pinned sidecar

  organization-healthcheck:
    image: curlimages/curl:8.11.1@sha256:6f9a56e1a5ffa0e2b0c8ba61aacd8ba4b9f6d18e8b9e88a8a4b93b9c99a67320
    # ...

Pinning by digest here means this specific sidecar's behavior cannot change under the same tag between one developer's laptop and another's, or between a laptop and CI.

Verify Migrate-Then-Serve, Not Just That 'docker compose up' Exits Zero

Terminal — repository root

$docker compose up --build organization-migrate organization

// Builds both targets from the same Dockerfile and starts them in dependency order.

$docker compose ps

// organization-migrate should show 'Exited (0)' — anything else means a migration failed and organization correctly never started.

$docker compose --profile verify run --rm organization-healthcheck

// Exercises the disposable sidecar on demand, proving the running organization container answers correctly from outside its own network namespace, not just from its own healthcheck's perspective.

Fail the Stack Loudly When a Migration Fails, Never Silently

docker compose ps after an intentionally broken migration

NAME                    IMAGE                                          STATUS
compose-postgres-1      postgres:16.4                                  Up (healthy)
compose-organization-migrate-1  ghcr.io/hoa-platform/organization-migrate:local  Exited (1)
compose-organization-1  ghcr.io/hoa-platform/organization-api:local    Created

organization staying in 'Created' — never starting — is the depends_on service_completed_successfully condition working exactly as intended: a failed migration blocks the API from ever running against a schema it does not match, rather than starting against a half-applied database.

Applied exercise

Wire services/gateway-service into docker-compose.yml with the same discipline

20 minutes

services/gateway-service (from Lesson 1's exercise) has no Compose service yet and needs to reach organization by its Compose service name, not localhost.

Add a gateway service to docker-compose.yml, built from services/gateway-service/Dockerfile, running read-only and non-root.
Configure gateway's upstream URL for organization using the Compose service name organization, not localhost or a hardcoded IP.
Add a healthcheck using gateway's own in-process -healthcheck flag, following this lesson's pattern.
Verify with docker compose up that gateway only becomes healthy after organization itself reports healthy.

Deliverable

An updated docker-compose.yml with a working gateway service, verified end-to-end with a request that traverses gateway to organization.

Completion checks

gateway's upstream configuration references the Compose service name, never localhost.
gateway's healthcheck uses an in-process flag, not a shell command a distroless image cannot run.
A curl through gateway to an organization route succeeds only after both services report healthy.

Quiz & Practice

Question 1 / 2

Why does organization use depends_on with condition: service_completed_successfully on organization-migrate, instead of the default service_started condition?

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.

Course outline

01 · Phase 1 — Project Foundation16/16

02 · Phase 2 — Organization Service20/20

03 · Phase 3 — User Service10/10

04 · Phase 4 — Authentication Service10/10

05 · Phase 5 — API Gateway9/9

06 · Phase 6 — Flat Service6/6

07 · Phase 7 — Resident Service7/7

08 · Phase 8 — Maintenance Service7/7

09 · Phase 9 — Payment Service7/7

10 · Phase 10 — Complaint Service7/7

11 · Phase 11 — Notice Service7/7

12 · Phase 12 — Visitor Service6/6

13 · Phase 13 — Staff Service6/6

14 · Phase 14 — Notification Service7/7

15 · Phase 15 — Redis Integration6/6

16 · Phase 16 — Kafka Integration8/8

17 · Phase 17 — Observability7/7

18 · Phase 18 — Performance Engineering6/6

19 · Phase 19 — Production Deployment11/11

20 · Phase 20 — Production Readiness8/8

Stage 7 · Master

Phase 19 — Production Deployment

Docker Compose

14 min readHOA Backend Engineering CourseMaster

A Local Stack That Diverges From Production Teaches the Wrong Lessons

Terminal — repository root

$touch compose.override.local.yaml

// Compose's file merge semantics let a small override file add the organization service without duplicating postgres/redis definitions already in docker-compose.yml.

Create docker-compose.yml before adding the code

$touch docker-compose.yml

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

docker-compose.yml — organization-migrate, organization, and organization-healthcheck additions

services:
  organization-migrate:
    build:
      context: .
      dockerfile: services/organization/Dockerfile
      target: migrate
    image: ghcr.io/hoa-platform/organization-migrate:local
    command: ["-path", "/app/migrations", "-database", "${MIGRATE_DATABASE_URL}", "up"]
    depends_on:
      postgres:
        condition: service_healthy
    restart: "no" # a one-shot job must never restart itself into a crash loop

  organization:
    build:
      context: .
      dockerfile: services/organization/Dockerfile
      target: api
    image: ghcr.io/hoa-platform/organization-api:local
    read_only: true
    user: "65532:65532"
    environment:
      DATABASE_URL: ${DATABASE_URL}
      REDIS_ADDRESS: redis:6379
      ORGANIZATION_HTTP_ADDR: :8081
    ports:
      - "8081:8081"
      - "9090:9090" # internal listener: healthz, readyz, metrics
    depends_on:
      organization-migrate:
        condition: service_completed_successfully
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "/app/organization-api", "-healthcheck"] # a distroless image has no curl or wget to shell out to
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 5s

  organization-healthcheck:
    image: curlimages/curl:8.11.1
    depends_on:
      organization:
        condition: service_healthy
    command: ["curl", "-sf", "http://organization:9090/healthz"]
    profiles: ["verify"] # disposable — only runs when explicitly requested, never as part of a normal 'up'

MIGRATE_DATABASE_URL is a second .env value, not a typo of DATABASE_URL

A distroless image has no shell for a traditional HEALTHCHECK

Create services/organization/cmd/api/main.go before adding the code

$mkdir -p services/organization/cmd/api && touch services/organization/cmd/api/main.go

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/organization/cmd/api/main.go — healthcheck flag addition

func main() {
	healthcheckMode := flag.Bool("healthcheck", false, "perform an in-process liveness check and exit")
	flag.Parse()

	if *healthcheckMode {
		resp, err := http.Get("http://localhost:9090/healthz")
		if err != nil || resp.StatusCode != http.StatusOK {
			os.Exit(1)
		}
		os.Exit(0)
	}

	// ... normal server startup continues below
}

Pin Every Image Compose Does Not Build From This Repository

Terminal — repository root

$docker buildx imagetools inspect curlimages/curl:8.11.1 --format '{{json .Manifest.Digest}}'

// Resolves today's real digest — run this yourself rather than trusting a value printed in a lesson written on a different day.

Create docker-compose.yml before adding the code

$touch docker-compose.yml

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

docker-compose.yml — digest-pinned sidecar

  organization-healthcheck:
    image: curlimages/curl:8.11.1@sha256:6f9a56e1a5ffa0e2b0c8ba61aacd8ba4b9f6d18e8b9e88a8a4b93b9c99a67320
    # ...

Pinning by digest here means this specific sidecar's behavior cannot change under the same tag between one developer's laptop and another's, or between a laptop and CI.

Verify Migrate-Then-Serve, Not Just That 'docker compose up' Exits Zero

Terminal — repository root

$docker compose up --build organization-migrate organization

// Builds both targets from the same Dockerfile and starts them in dependency order.

$docker compose ps

// organization-migrate should show 'Exited (0)' — anything else means a migration failed and organization correctly never started.

$docker compose --profile verify run --rm organization-healthcheck

// Exercises the disposable sidecar on demand, proving the running organization container answers correctly from outside its own network namespace, not just from its own healthcheck's perspective.

Fail the Stack Loudly When a Migration Fails, Never Silently

docker compose ps after an intentionally broken migration

NAME                    IMAGE                                          STATUS
compose-postgres-1      postgres:16.4                                  Up (healthy)
compose-organization-migrate-1  ghcr.io/hoa-platform/organization-migrate:local  Exited (1)
compose-organization-1  ghcr.io/hoa-platform/organization-api:local    Created

Applied exercise

Wire services/gateway-service into docker-compose.yml with the same discipline

20 minutes

services/gateway-service (from Lesson 1's exercise) has no Compose service yet and needs to reach organization by its Compose service name, not localhost.

Add a gateway service to docker-compose.yml, built from services/gateway-service/Dockerfile, running read-only and non-root.
Configure gateway's upstream URL for organization using the Compose service name organization, not localhost or a hardcoded IP.
Add a healthcheck using gateway's own in-process -healthcheck flag, following this lesson's pattern.
Verify with docker compose up that gateway only becomes healthy after organization itself reports healthy.

Deliverable

An updated docker-compose.yml with a working gateway service, verified end-to-end with a request that traverses gateway to organization.

Completion checks

gateway's upstream configuration references the Compose service name, never localhost.
gateway's healthcheck uses an in-process flag, not a shell command a distroless image cannot run.
A curl through gateway to an organization route succeeds only after both services report healthy.

Quiz & Practice

Question 1 / 2

Why does organization use depends_on with condition: service_completed_successfully on organization-migrate, instead of the default service_started condition?

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.