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

Environment Variables

Load .env for local development without letting it silently outrank a real environment variable set by CI, a container, or a teammate's shell.

15 min readHOA Backend Engineering CourseMaster

Why Precedence Order Is a Correctness Issue

A .env file is a convenience for local development: it lets a contributor set ORGANIZATION_PORT once in a file instead of exporting it in every new terminal tab. The moment that convenience is allowed to override a variable a deployment platform, a CI runner, or a Kubernetes ConfigMap already set, it stops being a convenience and becomes a source of an entire class of 'works on my machine, breaks in staging' bugs. The rule this lesson enforces is simple and non-negotiable: a real environment variable always wins over a .env file, and a .env file always wins over a struct default.

Loading .env in Exactly One Place

Terminal — services/organization

$go get github.com/joho/godotenv@v1.5.1

// Adds godotenv to services/organization/go.mod — a per-service dependency, not shared through pkg/.

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 (modify — one new line before config.Load)

// Load local defaults before config.Load reads the process environment.
// Load does not overwrite keys already exported by the shell or runtime.
_ = godotenv.Load()

The rest of main.go is unchanged and is not printed again. godotenv.Load is called exactly once before config.Load—never inside internal/config or a test helper—so precedence has one visible owner.

godotenv.Load never overrides an already-set variable

godotenv's Load function sets a key from the .env file only if that key is not already present in the process environment. This is exactly the precedence this lesson needs: export ORGANIZATION_PORT=7070 in a shell before running go run ./cmd/api, and the .env file's ORGANIZATION_PORT is ignored for that run — no extra code required.

.env.example as Executable Documentation

Terminal — repository root

$touch .env.example

// Committed. The real .env is already excluded by the .gitignore from the Monorepo Setup lesson.

Create .env.example before adding the code

$touch .env.example

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

.env.example

# Copy to .env and adjust for local development.
# Real environment variables (CI, containers, Kubernetes) always take
# precedence over this file — see the Environment Variables lesson.

ORGANIZATION_ENV=development
ORGANIZATION_PORT=8080

What CI and Containers Must Never Do

Neither a GitHub Actions runner nor the Dockerfile built in Phase 2 ever ships a .env file into its environment. Both set the real variables they need directly (as workflow env: keys, or as Kubernetes ConfigMap-sourced environment variables) and rely on godotenv.Load's no-op behavior when no .env file is present. Copying .env.example into .env inside a CI pipeline, thinking it 'documents' the defaults, would instead reintroduce exactly the precedence risk this lesson exists to prevent, if any real variable were ever misconfigured to be absent.

Proving Precedence, Not Just Believing It

Terminal — services/organization

$cp ../../.env.example .env && sed -i '' 's/8080/9090/' .env

// Local .env now claims port 9090 (use sed -i without '' on Linux).

$go run ./cmd/api &

// No OS-level override set — expect the .env value, 9090, to win.

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

// Confirms .env took effect.

$kill %1

$ORGANIZATION_PORT=7070 go run ./cmd/api &

// Now an explicit OS environment variable is set alongside the same .env file.

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

// Confirms the OS variable, not the .env file, won.

$kill %1

A malformed .env line fails godotenv.Load, but this service treats that failure as non-fatal

A line like PORT 8080 (missing the =) makes godotenv.Load return a parse error. Because that error is discarded with _ = godotenv.Load(), a broken .env file today silently falls through to real environment variables and struct defaults instead of crashing the service — acceptable for a local convenience file, but worth knowing: a bad .env fails silently, not loudly, and struct defaults from the Configuration Management lesson are the safety net.

Applied exercise

Prove that a missing .env file is not treated as an error

10 minutes

The main.go change ignores godotenv.Load's return value. Confirm that decision is intentional and safe, not an oversight.

Delete the local .env file entirely (mv it aside, don't just clear it).
Run go run ./cmd/api and confirm the service starts using struct defaults from Configuration Management.
Temporarily change the ignored error to log.Printf("godotenv: %v", err) and rerun without a .env file to see the exact message godotenv produces for a missing file.
Revert the temporary logging change — production behavior stays silent on a missing .env, as documented in this lesson.

Deliverable

A short note recording the exact log line godotenv produces for a missing .env file, and confirmation the service still starts.

Completion checks

The service starts successfully with no .env file present.
The temporary debug log line is reverted before finishing — main.go matches this lesson's version exactly.

Quiz & Practice

Question 1 / 1

If both a .env file and a real OS environment variable set ORGANIZATION_PORT to different values, which one does the running service use?

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

Environment Variables

Load .env for local development without letting it silently outrank a real environment variable set by CI, a container, or a teammate's shell.

15 min readHOA Backend Engineering CourseMaster

Why Precedence Order Is a Correctness Issue

Loading .env in Exactly One Place

Terminal — services/organization

$go get github.com/joho/godotenv@v1.5.1

// Adds godotenv to services/organization/go.mod — a per-service dependency, not shared through pkg/.

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 (modify — one new line before config.Load)

// Load local defaults before config.Load reads the process environment.
// Load does not overwrite keys already exported by the shell or runtime.
_ = godotenv.Load()

godotenv.Load never overrides an already-set variable

.env.example as Executable Documentation

Terminal — repository root

$touch .env.example

// Committed. The real .env is already excluded by the .gitignore from the Monorepo Setup lesson.

Create .env.example before adding the code

$touch .env.example

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

.env.example

# Copy to .env and adjust for local development.
# Real environment variables (CI, containers, Kubernetes) always take
# precedence over this file — see the Environment Variables lesson.

ORGANIZATION_ENV=development
ORGANIZATION_PORT=8080

What CI and Containers Must Never Do

Proving Precedence, Not Just Believing It

Terminal — services/organization

$cp ../../.env.example .env && sed -i '' 's/8080/9090/' .env

// Local .env now claims port 9090 (use sed -i without '' on Linux).

$go run ./cmd/api &

// No OS-level override set — expect the .env value, 9090, to win.

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

// Confirms .env took effect.

$kill %1

$ORGANIZATION_PORT=7070 go run ./cmd/api &

// Now an explicit OS environment variable is set alongside the same .env file.

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

// Confirms the OS variable, not the .env file, won.

$kill %1

A malformed .env line fails godotenv.Load, but this service treats that failure as non-fatal

Applied exercise

Prove that a missing .env file is not treated as an error

10 minutes

The main.go change ignores godotenv.Load's return value. Confirm that decision is intentional and safe, not an oversight.

Delete the local .env file entirely (mv it aside, don't just clear it).
Run go run ./cmd/api and confirm the service starts using struct defaults from Configuration Management.
Temporarily change the ignored error to log.Printf("godotenv: %v", err) and rerun without a .env file to see the exact message godotenv produces for a missing file.
Revert the temporary logging change — production behavior stays silent on a missing .env, as documented in this lesson.

Deliverable

A short note recording the exact log line godotenv produces for a missing .env file, and confirmation the service still starts.

Completion checks

The service starts successfully with no .env file present.
The temporary debug log line is reverted before finishing — main.go matches this lesson's version exactly.

Quiz & Practice

Question 1 / 1

If both a .env file and a real OS environment variable set ORGANIZATION_PORT to different values, which one does the running service use?

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