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 1 — Project Foundation

Docker Development Environment

Stand up one docker-compose.yml the whole team runs identically, before wiring a single real dependency into it.

14 min readHOA Backend Engineering CourseMaster

Why Local Compose Instead of a Shared Cloud Dev Database

A shared cloud development database sounds convenient until two contributors' migrations collide, or a load test from one laptop degrades everyone's afternoon. docker-compose.yml gives every contributor an identical, disposable, entirely local copy of every infrastructure dependency the platform will need — PostgreSQL, Redis, and Kafka, added one at a time over the next three lessons — with zero risk of cross-contamination between machines.

Terminal — repository root

$touch .dockerignore docker-compose.yml

// Both created before any service is defined.

Create .dockerignore before adding the code

$touch .dockerignore

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

.dockerignore

.git
**/bin
*.log
.env
.env.*
!.env.example

A Compose Skeleton: Project Name, Network, and One Harmless Service

Rather than leave the services key empty — which is technically valid YAML but proves nothing runs — this skeleton includes one lightweight, dependency-free service: Adminer, a web-based database browser. It has nothing to connect to yet, but it proves the network, the compose project name, and the up/down lifecycle all work before PostgreSQL exists to depend on any of them, and it stays useful once Postgres does exist in the next lesson.

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

name: hoa-platform

networks:
  hoa-net:
    driver: bridge

services:
  adminer:
    image: adminer:4.8.1
    restart: unless-stopped
    ports:
      - "8081:8080"
    networks:
      - hoa-net

Why the Top-Level name: Key Is Not Optional

Without an explicit name:, Docker Compose derives a project name from the current directory's basename. Two clones of hoa-platform on the same machine — a common setup when reviewing a colleague's branch alongside your own working copy — would then produce two different project names (hoa-platform and hoa-platform-2, for instance) or, worse, the same name if both directories happen to share a basename, silently sharing networks and named volumes between two supposedly independent checkouts. Pinning name: hoa-platform makes the project identity a property of the file, not of wherever it happens to be checked out.

Validating and Running the Skeleton

Terminal — repository root

$docker compose config

// Validates the YAML and prints the fully resolved configuration — catches typos before anything starts.

$docker compose up -d adminer

// Starts only the adminer service.

$curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8081/

// Expect 200 — Adminer's login page.

$docker compose down

// Tears everything down cleanly.

This is intentionally the only lesson that adds a service with nothing to connect to

Adminer stays a standalone, ready-to-browse UI once PostgreSQL exists in the next lesson — it does not get removed once real dependencies arrive, it gets more useful.

Applied exercise

Confirm the project name actually isolates two checkouts

12 minutes

The reasoning above about name: is easy to accept and easy to never verify. Verify it.

Clone the repository a second time into a differently-named directory (for example hoa-platform-review).
Run docker compose up -d adminer from both checkouts at once.
Run docker network ls and docker compose ls from either checkout and confirm two independent projects and networks exist, both named consistently as hoa-platform, without a numeric suffix collision.
Tear both down with docker compose down from each directory.

Deliverable

A short note recording the output of docker compose ls showing both project instances active at once.

Completion checks

Both checkouts' Adminer containers respond on their respective mapped ports simultaneously.
Both instances are torn down at the end — docker compose ls shows none remaining.

Quiz & Practice

Question 1 / 1

What would happen if docker-compose.yml omitted the top-level name: key?

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 1 — Project Foundation

Docker Development Environment

Stand up one docker-compose.yml the whole team runs identically, before wiring a single real dependency into it.

14 min readHOA Backend Engineering CourseMaster

Why Local Compose Instead of a Shared Cloud Dev Database

Terminal — repository root

$touch .dockerignore docker-compose.yml

// Both created before any service is defined.

Create .dockerignore before adding the code

$touch .dockerignore

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

.dockerignore

.git
**/bin
*.log
.env
.env.*
!.env.example

A Compose Skeleton: Project Name, Network, and One Harmless Service

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

name: hoa-platform

networks:
  hoa-net:
    driver: bridge

services:
  adminer:
    image: adminer:4.8.1
    restart: unless-stopped
    ports:
      - "8081:8080"
    networks:
      - hoa-net

Why the Top-Level name: Key Is Not Optional

Validating and Running the Skeleton

Terminal — repository root

$docker compose config

// Validates the YAML and prints the fully resolved configuration — catches typos before anything starts.

$docker compose up -d adminer

// Starts only the adminer service.

$curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8081/

// Expect 200 — Adminer's login page.

$docker compose down

// Tears everything down cleanly.

This is intentionally the only lesson that adds a service with nothing to connect to

Adminer stays a standalone, ready-to-browse UI once PostgreSQL exists in the next lesson — it does not get removed once real dependencies arrive, it gets more useful.

Applied exercise

Confirm the project name actually isolates two checkouts

12 minutes

The reasoning above about name: is easy to accept and easy to never verify. Verify it.

Clone the repository a second time into a differently-named directory (for example hoa-platform-review).
Run docker compose up -d adminer from both checkouts at once.
Run docker network ls and docker compose ls from either checkout and confirm two independent projects and networks exist, both named consistently as hoa-platform, without a numeric suffix collision.
Tear both down with docker compose down from each directory.

Deliverable

A short note recording the output of docker compose ls showing both project instances active at once.

Completion checks

Both checkouts' Adminer containers respond on their respective mapped ports simultaneously.
Both instances are torn down at the end — docker compose ls shows none remaining.

Quiz & Practice

Question 1 / 1

What would happen if docker-compose.yml omitted the top-level name: key?

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