Nexus-Guard-Suite/.omo/plans/archived/docker-swagger-fix.md

Docker Build Fix — Swagger docs.go Not Found

TL;DR

Quick Summary: The Swagger-generated file docs/docs.go is .gitignore-d, so Docker build fails with no required module provides package .../docs. Fix: add swag init step in the Dockerfile builder stage so docs are generated during build before compilation.

Deliverables:

• Dockerfile updated with swag init before go build
• Docker build succeeds without error

Estimated Effort: Trivial (single-line addition) Parallel Execution: N/A (single task)

---

Context

Original Request

Docker build fails with:

main.go:17:2: no required module provides package git.datadunia.com/nexusguard/nexus-server-core/docs

Root cause: apps/server-core/.gitignore (lines 40-43) ignores docs/docs.go, docs/swagger.json, docs/swagger.yaml. These files were generated locally by swag init but are gitignored. When docker build runs COPY . ., these files are not included, so the Go compilation fails because main.go has _ "git.datadunia.com/nexusguard/nexus-server-core/docs".

Metis Analysis

• Must pin swag CLI version to match go.mod: v1.16.6
• Must keep .gitignore as-is (generated files should not be tracked)
• No other files cause similar issues — audit confirmed
• Build tag approach is unnecessary complexity

---

Work Objectives

Core Objective

Make Docker build succeed with Swagger docs generated during build process.

Must Have

• apps/server-core/Dockerfile runs swag init before go build ✅
• swag init uses pinned CLI version matching go.mod (v1.16.6) ✅
• docker compose build server-core passes (verified on remote Docker host) ✅

Must NOT Have

• Do NOT remove swagger files from .gitignore
• Do NOT restructure main.go with build tags
• Do NOT modify Makefile or any other files

---

Execution Strategy

Single task, no waves needed.

---

TODOs

• 1. Fix Dockerfile — Add swag init in builder stage (ALREADY APPLIED — Dockerfile line 7 sudah ada swag init)

  What to do:

  • Edit apps/server-core/Dockerfile
  • Between COPY . . and RUN CGO_ENABLED=0 go build -o /app/server-core ., add:

    RUN go install github.com/swaggo/swag/cmd/swag@v1.16.6 && swag init -g main.go --parseDependency --parseInternal
    

  • This runs swag CLI pinned to v1.16.6 (matching go.mod), generates docs/docs.go, then Go compliation finds the package.

  Final Dockerfile should look like:

  # Stage 1: Builder
  FROM golang:1.25-alpine AS builder
  WORKDIR /app
  COPY go.mod go.sum ./
  RUN go mod download
  COPY . .
  RUN go install github.com/swaggo/swag/cmd/swag@v1.16.6 && swag init -g main.go --parseDependency --parseInternal
  RUN CGO_ENABLED=0 go build -o /app/server-core .
  

  Recommended Agent Profile:

  • Category: quick
  • Skills: []

  Parallelization: Single task

  References:

  • apps/server-core/Dockerfile — Current Dockerfile (multi-stage, golang:1.25-alpine)
  • apps/server-core/.gitignore:40-43 — Lines that gitignore swagger output
  • apps/server-core/main.go:17 — Import of _ "docs" package

  Acceptance Criteria:

  • docker build -f apps/server-core/Dockerfile -t nexusguard-server-core apps/server-core succeeds (exit 0) ✅
  • Swagger route /swagger/index.html works when container runs (HTTP 200) ✅

  QA Scenarios:

  Scenario: Docker build succeeds with swagger docs generated
    Tool: Bash
    Preconditions: Docker is installed, at project root
    Steps:
      1. docker build -f apps/server-core/Dockerfile -t nexusguard-server-core apps/server-core
      2. echo "Exit: $?"
    Expected Result: Build completes without errors (exit 0)
    Failure Indicators: Error about missing docs package
    Evidence: .sisyphus/evidence/task-1-docker-build-success.txt
  
  Scenario: Make not installed — fallback works
    Tool: Bash
    Preconditions: make is NOT installed (simulate with `which make || true`)
    Steps:
      1. docker compose build server-core
      2. docker compose up -d
    Expected Result: Services start without requiring `make`
    Failure Indicators: `make: command not found` blocks deployment
    Evidence: .sisyphus/evidence/task-1-direct-docker-compose.txt
  

---

Final Verification

• F1. Verify Dockerfile ✅ — swag init present on line 7 with correct version v1.16.6
• F2. Verify Docker Build ✅ — docker build exit 0, swag init generated docs.go, swagger.json, swagger.yaml during build
• F3. Verify Swagger ✅ — Container running on port 8080, curl /swagger/index.html → HTTP 200, valid Swagger HTML + JSON API spec returned

---

Commit Strategy

• 1: fix(server-core): generate swagger docs in Docker build step

---

Success Criteria

# Fix: Docker build
docker build -f apps/server-core/Dockerfile -t nexusguard-server-core apps/server-core
# Expected: Build successful, exit 0

# Verify no more make dependency
docker compose build server-core && docker compose up -d
# Expected: Services start