chore: remove nxg-fix-cors.md, add docker-swagger-fix.md plan
This commit is contained in:
datadunia
@@ -0,0 +1,146 @@
|
||||
# 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
|
||||
|
||||
### 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
|
||||
|
||||
**What to do**:
|
||||
- Edit `apps/server-core/Dockerfile`
|
||||
- Between `COPY . .` and `RUN CGO_ENABLED=0 go build -o /app/server-core .`, add:
|
||||
```dockerfile
|
||||
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:**
|
||||
```dockerfile
|
||||
# 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 test-fix apps/server-core` succeeds (exit 0)
|
||||
- [ ] Swagger route `/swagger/index.html` works when container runs
|
||||
|
||||
**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 Docker Build** — Run `docker build` and confirm exit 0
|
||||
- [ ] F2. **Verify Swagger** — Start container, `curl http://localhost:8080/swagger/index.html` returns 200
|
||||
- [ ] F3. **Verify Clean Environment** — Simulate fresh clone + build
|
||||
|
||||
---
|
||||
|
||||
## Commit Strategy
|
||||
|
||||
- **1**: `fix(server-core): generate swagger docs in Docker build step`
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user