Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIDeepSeekDeepSeekMuseMuse+22 more

    Go + React + Postgres Project Setup: Docker, Caddy, CI

    1

    - Pins Go, Node, PostgreSQL and key libraries, and explains the peer constraints that decide those versions.

    $9

    Secure checkout via Stripe

    Money-back guarantee

    Converts to your local currency at checkout

    Security scanned
    Go + React + Postgres Project Setup: Docker, Caddy, CI

    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 is DEV_PROXY_TARGET=http://backend:8080; when Vite runs on the host it falls back to http://localhost:8080.
    • Frontend code calls the relative path /api/v1/.... There is no VITE_API_URL, and nothing named VITE_* 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=None or a Domain attribute. 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 8080 to the host so you can curl it. Don't point browser code at localhost:8080; that's a second origin and the cookie breaks.

    Files created (nothing committed; README.md untouched)

    FileWhat it is
    docker-compose.ymlDev-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.sqlCreates 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/DockerfileMulti-stage build on golang:1.27.3-alpine producing a static binary on distroless, run as nonroot
    backend/go.modmodule teamboard/backend, go 1.27.3. The module path is a placeholder until the repo has a remote
    backend/sqlc.yamlschema: "../migration", queries: "db/queries", pgx/v5
    frontend/vite.config.tsDev server: /api/v1 proxy, strictPort, polling switched by an env var
    frontend/package.jsonExact 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
    .nvmrc26.13.0
    MakefileThe nine gates plus make db
    scripts/version-check.shThe body of the make version-check gate
    migration/README.mdWhich role runs migrations, file-naming rules, the reset procedure, and what to do when a failed migration leaves the database marked dirty
    docs/DECISIONS.mdDesign stage, layout, same-origin rule, roles, pins and held-back versions, gate status, and the decided secret-scan exemption
    deployment/.gitkeep, observability/.gitkeepReserved, empty. Their contents depend on a deploy target nobody has chosen yet
    .gitignorenode_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-check and make secret-scan each print their TODO and exit non-zero, as intended.
    • make arch-test fails earlier than intended: /bin/sh: golangci-lint: command not found.
    • The backend half of make test fails 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

    1. docker compose up will not get all the way up yet. Four things block it:

      • migration/ is empty, so migrate up fails and the backend waits on it forever. The first migration comes from the schema design.
      • The backend has no cmd/api and no go.sum, so the image can't build.
      • frontend/ has no package-lock.json, so npm ci fails. I couldn't generate one without downloading packages. Run npm install once on the host with Node 26.13.0, commit the lockfile, and never run npm install inside the container.
      • There's no index.html or src/ yet; those belong to the frontend work.

      Until then, make db brings 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

    Generated

    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/v1 and cookies just work.
    • Separates database roles instead of using one superuser connection.
    • Defines the gate set as make targets 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, backend Dockerfile, 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) and check-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.

    Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for APIs & Backend.

    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. 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. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before buying a skill.

    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

    Accounts
    GolangGoEndoflife
    Software
    DockerDocker Compose v2Go toolchainNode.jsMakeBashcurl and python3 (for check-pins.sh)Gittsceslintvitest

    Permissions

    Terminal / Shell
    Network Access
    Read Files
    Write Files

    Allowed Hosts

    proxy.golang.org
    go.dev
    endoflife.date
    hub.docker.com
    registry.npmjs.org

    File Scopes

    docker-compose.yml
    Caddyfile
    Makefile
    **/Dockerfile
    .nvmrc
    go.mod
    frontend/vite.config.ts
    migration/**
    .github/workflows/**

    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.

    Listed8 days ago

    What's inside

    Frequently Asked Questions

    No. It is built for a Vite single-page app served next to a Go API, from one origin.

    They are current as of the skill's last update. scripts/check-pins.sh compares them with the latest upstream versions, and scripts/version-check.sh fails when Node or Go versions disagree across your files.

    No. It sets the structure: layout, local stack, proxying, database roles, gates and CI shape. Feature code is out of scope.

    The browser only ever talks to one origin: the Vite dev server proxies /api to the Go API, and Caddy does the same in staging and production. The API base is the relative /api/v1, so there is no cross-origin cookie or CORS setup to get wrong.

    No. It shapes CI up to the artifact. Shipping to a server is out of scope.

    Only scripts/check-pins.sh, and only when you or the agent run it: read-only GET requests to public version endpoints plus npm view. Nothing is uploaded.

    New in APIs & Backend