klickops starter

A rock-solid starting point for building a web app: SvelteKit frontend + Go backend in a single container, with optional PostgreSQL and S3 storage wired the way klickops provides them.

It is a seed, not a framework. Everything in here is meant to be understood in an afternoon and replaced by your own app. It ships with the guardrails that make AI-assisted development work well: a CLAUDE.md brief, coding rules, a feature recipe, tests, CI, and Dependabot.

Deutsche Version: README.de.md

What you get

• One container that serves the API (/api/*) and the built UI. One Dockerfile, one deployable artifact, no orchestration puzzle.
• Go backend on the standard library (no framework), with a tiny embedded SQL migration runner and graceful degradation: the app starts and runs even before a database or bucket is bound.
• SvelteKit 5 + Tailwind 4 frontend as a static SPA, with a small design-token system (automatic dark mode) and a few UI primitives.
• Working examples: a notes CRUD (PostgreSQL) and file upload/download (S3). Delete them once your real app takes shape.
• AI guidance built in: CLAUDE.md, .claude/rules/, and a step-by-step new-feature skill so Claude Code, Cursor, and friends extend the app idiomatically instead of inventing their own patterns.
• Quality gates: Go and frontend tests, make check, GitHub Actions CI (format, vet, type-check, test, build, Docker build), and Dependabot keeping Go, npm, Actions, and base images up to date.

Quick start

Use this repo as a GitHub template ("Use this template" button), then either open your new repo in GitHub Codespaces (the included devcontainer preinstalls Go, Node, pnpm, and Docker - no local setup at all) or work locally:

git clone git@github.com:you/your-app.git
cd your-app
make install        # frontend dependencies (needs pnpm)
make dev            # backend on :8080, frontend on :5173

Open http://localhost:5173. The app runs with zero configuration; the database and storage sections show how to enable them.

To develop with real services locally (needs Docker):

make services-up          # PostgreSQL + S3-compatible server
cp .env.example .env      # points at those services
make dev

Build it with AI

This repo is written to be extended by AI coding tools. Open the folder with Claude Code (or Cursor, etc.) and describe what you want:

"Replace the notes demo with a customer list: name, email, a note field, and a CSV export."

The AI reads CLAUDE.md for the architecture, .claude/rules/ for the coding conventions, and .claude/skills/new-feature/ for the exact recipe to add a feature end to end (migration, handler, tests, UI). Ask it to run make check && make test before it declares victory; CI enforces the same.

Deploy on klickops

1. Push your repo to GitHub.

2. In klickops: create a project, Deploy from repo, pick the repo. klickops detects the Dockerfile, builds it, and deploys the container with a URL and TLS.

3. Database: add a PostgreSQL service to the project. klickops sees the DATABASE_URL variable declared in the Dockerfile and suggests the binding, accept it and the app connects and migrates on the next start.

4. Storage: add a Bucket service and bind it to the app with these outputs:

   Env var	Binding template
   S3_ENDPOINT	{{ .svc.endpoint }}
   S3_REGION	{{ .svc.region }}
   S3_BUCKET	{{ .svc.bucket }}
   S3_ACCESS_KEY	{{ .svc.user }}
   S3_SECRET_KEY	{{ .svc.password }}

No YAML, no kubectl. Any other container platform works too, the app only needs the env vars below.

Configuration

Everything is an environment variable with a sensible default (internal/config/config.go is the single source of truth):

Variable	Default	Purpose
PORT	8080	HTTP listen port
DATABASE_URL	(unset)	PostgreSQL connection string; unset = notes API disabled
S3_ENDPOINT	(unset)	S3-compatible endpoint (host:port or URL)
S3_REGION	us-east-1	S3 signing region
S3_BUCKET	(unset)	bucket name; unset = files API disabled
S3_ACCESS_KEY / S3_SECRET_KEY	(unset)	bucket credentials
UI_DIR	ui/build	where the built SPA lives

Project structure

cmd/server/             Go entry point (config, wiring, graceful shutdown)
internal/config/        env var parsing, the only place os.Getenv appears
internal/api/           HTTP handlers + store interfaces + tests
internal/db/            pgx pool, embedded SQL migrations, store impls
internal/storage/       S3 implementation
ui/src/routes/          SvelteKit pages (SPA)
ui/src/lib/api/         typed fetch wrappers
ui/src/lib/components/  design-system primitives
.claude/                rules + skills that guide AI coding tools
.devcontainer/          GitHub Codespaces / devcontainer setup

Commands

make help            # list all commands
make dev             # run backend + frontend for development
make check           # type-check everything
make test            # run all tests
make lint            # formatting + vet checks
make build           # production build (bin/server + ui/build)
make docker-build    # build the container image

License

MIT. Build something.