- Home
- Skills
- APIs & Backend
- Go + React + Postgres Project Setup: Docker, Caddy, CI
Works with the AI Agents you already use
Go + React + Postgres Project Setup: Docker, Caddy, CI
- Pins Go, Node, PostgreSQL and key libraries, and explains the peer constraints that decide those versions.
$9
Go + React + Postgres Project Setup: Docker, Caddy, CI
Example session with this skill installed
Start a new project: Go API, React with Vite, Postgres. Set up the repo layout and a local Docker Compose stack where login cookies work in dev.
- Read your context and instructions
- Compiled the go + react
- Generated the document
teamboard: repo layout and local stack are in place; the project is still in design
Where the project stands. The only product statement in the repo is the README line: "users log in, create boards and move cards." There is no API contract, no schema and no product brief yet, so this is still the design phase. The layout, the local stack and the gates don't depend on product decisions, so I set all three up. I did
not write any feature code: no login endpoint, no handlers, no components, and no first migration. Those come out of the design work listed under next steps.
How login cookies work in dev
The browser only ever talks to one origin, http://localhost:5173:
- Vite's dev server forwards
/api/v1/*to the backend. In compose the target isDEV_PROXY_TARGET=http://backend:8080; when Vite runs on the host it falls back tohttp://localhost:8080. - Frontend code calls the relative path
/api/v1/.... There is noVITE_API_URL, and nothing namedVITE_*may point at an API host, because that prefix gets baked into the browser bundle. - So a session cookie set by the API is an ordinary host-only cookie on the page's own origin. You don't need CORS,
SameSite=Noneor aDomainattribute. Loosening those to make dev work is exactly the change that would then ship to production. - In production, Caddy does the same job and the browser still sees one origin.
- ⚠ The backend publishes
8080to the host so you can curl it. Don't point browser code atlocalhost:8080; that's a second origin and the cookie breaks.
Files created (nothing committed; README.md untouched)
| File | What it is |
|---|---|
docker-compose.yml | Dev-only stack (name: teamboard): postgres:18.6-alpine, a one-shot migrate/migrate:v4.20.1 running as app_owner, backend (built from ./backend, connects as app_user), and frontend on node:26.13.0-alpine running Vite on 5173 |
local/postgres-init/01-roles.sql | Creates two roles: app_owner (owns the schema, runs migrations) and app_user (the app, owns nothing), plus default grants. The superuser is used only by this script |
backend/Dockerfile | Multi-stage build on golang:1.27.3-alpine producing a static binary on distroless, run as nonroot |
backend/go.mod | module teamboard/backend, go 1.27.3. The module path is a placeholder until the repo has a remote |
backend/sqlc.yaml | schema: "../migration", queries: "db/queries", pgx/v5 |
frontend/vite.config.ts | Dev server: /api/v1 proxy, strictPort, polling switched by an env var |
frontend/package.json | Exact pins: react/react-dom 19.3.1, vite 8.3.6, @vitejs/plugin-react 6.2.1, typescript 6.0.3, typescript-eslint 8.72.1, eslint 10.14.0, vitest 4.1.12 |
.nvmrc | 26.13.0 |
Makefile | The nine gates plus make db |
scripts/version-check.sh | The body of the make version-check gate |
migration/README.md | Which role runs migrations, file-naming rules, the reset procedure, and what to do when a failed migration leaves the database marked dirty |
docs/DECISIONS.md | Design stage, layout, same-origin rule, roles, pins and held-back versions, gate status, and the decided secret-scan exemption |
deployment/.gitkeep, observability/.gitkeep | Reserved, empty. Their contents depend on a deploy target nobody has chosen yet |
.gitignore | node_modules/, dist/, .env, .env.* |
Checks run, and their output
1. Pin re-check (check-pins.sh, run before writing any version). All pins confirmed. Two are held back on purpose:
TypeScript stays on 6.0.3, not 7.0.2. typescript-eslint still requires typescript <6.1.0, so TS 7 would break make lint.
- Vitest stays on 4.1.12, not 5.1.0. A major version upgrade needs its changelog read first.
npm — latest, and the peers that are the half that matters
package latest pinned here | peers · engines
vite 8.3.6 8.3.6 | … · engines.node ^20.19.0 || >=22.12.0
@vitejs/plugin-react 6.2.1 6.2.1 | vite@^8.0.0 · oxc-transform-react@>=0.152.0 <0.157.0 · @rolldown/plugin-babel@^0.1.7 || ^0.2.0 || ^0.3.0 · babel-plugin-react-compiler@^1.0.0 · engines.node ^20.19.0 || >=22.12.0
react 19.3.1 19.3.1 | engines.node >=0.10.0
react-router 8.5.1 8.5.1 | react@>=19.2.7 · react-dom@>=19.2.7 · @types/react@>=19.2.0 · @types/react-dom@>=19.2.0 · engines.node >=22.22.0
typescript 7.0.2 6.0.3 | engines.node >=16.20.0
typescript-eslint 8.72.1 8.72.1 | eslint@^8.57.0 || ^9.0.0 || ^10.0.0 · typescript@>=4.8.4 <6.1.0 · engines.node ^18.18.0 || ^20.9.0 || >=21.1.0
eslint 10.14.0 10.14.0 | jiti@* · engines.node ^20.19.0 || ^22.13.0 || >=24
tailwindcss 4.3.5 4.3.5 | -
vitest 5.1.0 4.1.12 | vite@^6.4.0 || ^7.0.0 || ^8.0.0 · … · engines.node ^22.12.0 || ^24.0.0 || >=26.0.0
Go modules — latest, and that version's own 'go' directive (the floor it imposes)
Fiber v3.6.1 3.6.1 · needs go 1.26.0
pgx v5.12.0 5.12.0 · needs go 1.25.0
sqlc v1.31.1 1.31.1 · needs go 1.26.0
golang-migrate v4.20.1 4.20.1 · needs go 1.25.11
golangci-lint v2.15.0 2.15.0 · needs go 1.26.0
testcontainers-go v0.45.0 0.45.0 · needs go 1.26.0
OpenTelemetry Go v1.47.0 1.47.0 · needs go 1.26.0
Go toolchain
stable: go1.27.3, go1.27.2, go1.27.1
NOT stable (rc/beta): go1.27rc3, go1.27rc2, go1.27rc1
pinned here: 1.27.3
Node
26 latest 26.13.0 Active LTS eol 2029-04-30
24 latest 24.22.2 Maintenance LTS eol 2028-04-30
22 latest 22.23.4 Maintenance LTS eol 2027-04-30
pinned here: 26.13.0
PostgreSQL
18 latest 18.6 released 2026-08-11 eol 2030-11-14
pinned here: 18.6
Container tags
postgres (tags matching '18'): 18.6-alpine, 15.18-alpine, 18.4-alpine, …
node (tags matching '26'): 26.13.0-alpine, 26.13-alpine, 26.12.1-alpine, …
caddy (tags matching '2'): 2.11.9-alpine, 2.11-alpine, …
golang (tags matching '1.27'): 1.27.3-alpine, 1.27-alpine, 1.27.2-alpine, …
(I trimmed some long peer lists, marked with ….) The script does not check the migrate/migrate:v4.20.1 or distroless/static-debian12:nonroot image tags, so those two are unverified.
2. make version-check: passes.
Node
26.13.0 ./.nvmrc
26.13.0 ./docker-compose.yml
Go
1.27.3 ./backend/go.mod (go directive — a MINIMUM, not a pin)
1.27.3 ./backend/Dockerfile
version-check: OK
To confirm it actually catches drift, I ran it on a scratch copy with .nvmrc set to 24.7.0. It failed as it should: DISAGREE on major.minor: 24.7 26.13, exit=1.
3. docker compose config --quiet: exit=0. Services: postgres, migrate, backend, frontend. Images: postgres:18.6-alpine, migrate/migrate:v4.20.1, teamboard-backend, node:26.13.0-alpine.
4. The other gates. Five of the nine are expected to fail at this stage; each is listed in docs/DECISIONS.md with what closes it.
make rls-check,make migrate-check,make contract-checkandmake secret-scaneach print their TODO and exit non-zero, as intended.make arch-testfails earlier than intended:/bin/sh: golangci-lint: command not found.- The backend half of
make testfails because the local Go is too old:$ cd backend && GOTOOLCHAIN=local go build ./... go: go.mod requires go >= 1.27.3 (running go 1.25.0; GOTOOLCHAIN=local)
Not run: the frontend halves of make lint and make test. They call npx, which would download packages without a lockfile. make test-db and make db were also not run, and neither was docker compose up or docker build.
What does not work yet, and why
-
docker compose upwill not get all the way up yet. Four things block it:migration/is empty, somigrate upfails and the backend waits on it forever. The first migration comes from the schema design.- The backend has no
cmd/apiand nogo.sum, so the image can't build. frontend/has nopackage-lock.json, sonpm cifails. I couldn't generate one without downloading packages. Runnpm installonce on the host with Node 26.13.0, commit the lockfile, and never runnpm installinside the container.- There's no
index.htmlorsrc/yet; those belong to the frontend work.
Until then,
make dbbrings up Postgres alone (I didn't run it here).
Your local toolchain doesn't match the pins. Go is 1.25.0 against 1.27.3, and with GOTOOLCHAIN=local it refuses to build, so install Go 1.27.3. Node on the host is v24.7.0 against .nvmrc's 26.13.0, which matters for the faster workflow of running Vite on the host: docker compose stop frontend && cd frontend && npm run dev.
3. No golangci-lint, sqlc or migrate CLI is installed locally.
4.
Some frontend packages aren't added yet. react-router 8.5.1 and Tailwind 4.3.5 are the stack's pins, but nothing uses them yet. The type packages (@types/react, @types/react-dom, and @types/node, which vite.config.ts needs) and an ESLint config have no pinned versions. Add them on the host with exact versions.
5. No CI workflow and no Caddyfile. CI wasn't in this request; the Caddyfile waits for a deploy target.
Next steps: design, three tracks in parallel, each ending in a written document
Contract: every endpoint, including login and logout, with request/response shapes, the single error-code table and the pagination rule with its maximum page size.
Schema: tables, keys, constraints and indexes, written as the first migration/ up/down pair. This also settles how far to split the roles beyond two.
Interface: a product brief first (who it's for, what it must feel like, what it must never do), then screens, states and the design system.
Once those exist, building starts: backend test-first, the layered Go structure, then database queries and frontend work. The login cookie's own attributes are set in that backend work, against the contract.
index.html
PDF · document
Example file from a real run - the skill writes it into your workspace.
Connects securely to your tools. The creator never sees your data.
About this skill
The problem
Full-stack projects break at the seams, not in the features. A session cookie that never works in dev, a 404 on refresh, a VITE_API_URL baked into an image, a migration folder copied in two places, a CI check that differs from the one on your laptop, versions that drift between go.mod, the Dockerfile and CI.
What it does
- Lays out the repository and says what each directory must never contain.
- Pins Go, Node, PostgreSQL and key libraries, and explains the peer constraints that decide those versions.
- Runs the whole stack locally with one Docker Compose file: Go API, Vite dev server with HMR, Postgres, and a one-shot migration job.
- Serves everything from one origin (Vite proxy in dev, Caddy in staging and production), so the API base is always the relative
/api/v1and cookies just work. - Separates database roles instead of using one superuser connection.
- Defines the gate set as
maketargets so CI and a laptop run identical commands. - Shapes CI up to the artifact, and sets up logs, metrics and traces while keeping audit data out of the observability store.
- Diagnoses serving-path symptoms: cookies, refresh
404s, stale white screens,504s.
What's inside
SKILL.md: stack positioning and "one image, one origin, one schema, one command"- 10 references: repository layout, stack pins, local stack, environments, Caddy proxy, conventions, gates, CI, observability, routing
- 7 templates:
docker-compose.yml,Caddyfile,Makefile, backendDockerfile,postgres-init.sql,sqlc.yaml,vite.config.ts - 2 scripts:
version-check.sh(asserts Node and Go pins agree across.nvmrc,go.mod, Dockerfiles, CI and compose) andcheck-pins.sh(looks up current upstream versions)
Frameworks & tools
Go, React, Vite, PostgreSQL, Docker Compose, Caddy, sqlc, golang-migrate, Make, GitHub Actions.
Why this beats prompting it yourself
It makes the structural decisions once and explains each one: why there is no VITE_API_URL, why migration/ lives at the repository root, why configuration comes only from the environment, and why gates are make targets. It also ships a script that fails when your pinned versions drift apart.
Use cases
- Starting a new Go + React SaaS or internal tool.
- Restructuring a project that grew without a plan.
- Debugging a session cookie that works in production but not in dev.
- Deciding what CI must check before an artifact exists.
Known limitations
Vite SPA + Go API only, not Next.js. It owns structure, not feature code: it does not write handlers, components or SQL. Version pins reflect the date of the last update; run scripts/check-pins.sh to compare them with upstream. Deployment targets are out of scope.
Vite SPA + Go API only, not Next.js. It owns structure, not feature code: it does not write handlers, components or SQL. Version pins reflect the skill's last update; run scripts/check-pins.sh to compare them with upstream. Deployment targets are out of scope.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 8 days ago
Requires
Permissions
Allowed Hosts
File Scopes
Shell runs make targets, docker compose config and the two bundled scripts. Read and Write create the layout, compose file, Caddyfile, Makefile, Dockerfiles and config files. Network is used only by scripts/check-pins.sh, which makes read-only GET requests to proxy.golang.org, go.dev, endoflife.date and hub.docker.com, and runs npm view when npm is installed. Nothing is uploaded.