kereru-forms/README.md

Kererū Forms

Simple, versioned surveys with a Go + OpenAPI backend and a React frontend.

• Backend: Go 1.26, Gin, OpenAPI-generated server (oapi-codegen), SQLite via modernc.org/sqlite (pure Go), zerolog, OpenTelemetry.
• Frontend: React 18, Vite, TypeScript, Tailwind CSS, React Router, Vitest.
• Deployment: single container serving both the API and the built SPA, plus Docker Compose, Podman and Kubernetes manifests.

Quick start

1. Backend

cd backend
go mod download
go run ./cmd/kereru-forms --listen-addr 0.0.0.0 --port 8080

The API listens on http://localhost:8080. The SQLite database (kereru.db) and its schema are created automatically.

2. Frontend

cd frontend
npm install
npm run dev

Open http://localhost:5173. Vite proxies /api/* to http://localhost:8080/api/*. The API is also available without the /api prefix for probes and direct clients.

Configuration

Settings are resolved in this order (highest wins):

1. CLI flags
2. Environment variables
3. .env file next to the executable, then the working directory
4. YAML/JSON file passed with --conf
5. Built-in defaults

kereru-forms --conf ./config/config.example.yaml

Flag	Environment variable	Default
--conf	–	–
--log-level	KERERU_LOG_LEVEL	info
--log-format	KERERU_LOG_FORMAT	console
--listen-addr	KERERU_LISTEN_ADDR	0.0.0.0
--listen-addr6	KERERU_LISTEN_ADDR6	–
--port	KERERU_PORT	8080
--db-driver	KERERU_DB_DRIVER	sqlite
--db-dsn	KERERU_DB_DSN	file:kereru.db?...
--static-dir	KERERU_STATIC_DIR	–
–	KERERU_TELEMETRY_ENABLED	false
–	OTEL_EXPORTER_OTLP_ENDPOINT	localhost:4318
–	KERERU_CORS_ORIGINS	http://localhost:5173
–	KERERU_ENVIRONMENT	development

Both an IPv4 and an IPv6 listener may be configured at the same time. Set --listen-addr "" to disable the IPv4 listener.

Frontend build-time setting: VITE_API_BASE_URL (defaults to /api; set to http://localhost:8080 when the frontend is hosted separately).

Sample files live in config/.

API

The contract is defined in backend/openapi/openapi.yaml and the server stubs are generated with:

cd backend
oapi-codegen -config oapi-codegen.yaml openapi/openapi.yaml

Interactive API documentation is available at http://localhost:5173/docs. Swagger UI and the OpenAPI specification are bundled with the frontend, so the docs work without an internet connection. Forms support optional linked PDFs, digital signatures, external reference identifiers and offline PDF uploads.

Key routes:

Method	Path	Purpose
GET	/health	Health and version
GET/POST	/forms	List / create forms
GET/PUT/DELETE	/forms/{formId}	Read / update / delete a form version
POST	/forms/{formId}/activate	Activate a form version
POST	/forms/{formId}/inactivate	Inactivate a form version
POST	/forms/{formId}/versions	Clone into a new version
GET	/forms/{formId}/pdf	Printable PDF of the definition
GET/POST	/forms/{formId}/submissions	List / submit responses
GET	/submissions/{submissionId}	Submission details
GET	/submissions/{submissionId}/offline-pdf	Download an uploaded offline PDF
GET/POST	/forms/{formId}/access-codes	List / generate single-use codes

The specification is served at /openapi.yaml in development and production builds.

Tests

cd backend && go test ./...
cd frontend && npm test

Docker / Podman / Kubernetes

See docs/DEPLOYMENT.md and deploy/k8s.yaml.

Documentation

• docs/ARCHITECTURE.md — components, data model, request flow, extension points.
• docs/DEPLOYMENT.md — development, Docker, Podman and Kubernetes instructions.

Security note

The management endpoints are intentionally unauthenticated to match the current scope. Deploy behind an authenticating reverse proxy or add an auth layer before exposing management to untrusted networks. Access codes protect individual form submissions, not administration.