115 lines
4.3 KiB
Markdown
115 lines
4.3 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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/`](config).
|
||
|
||
## API
|
||
|
||
The contract is defined in [`backend/openapi/openapi.yaml`](backend/openapi/openapi.yaml) and the server stubs are generated with:
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
cd backend && go test ./...
|
||
cd frontend && npm test
|
||
```
|
||
|
||
## Docker / Podman / Kubernetes
|
||
|
||
See [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) and [`deploy/k8s.yaml`](deploy/k8s.yaml).
|
||
|
||
## Documentation
|
||
|
||
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — components, data model, request flow, extension points.
|
||
- [`docs/DEPLOYMENT.md`](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.
|