syafa/kibooz-backend repository overview

⁠Kibooz Backend

REST API for Kibooz, the kindergarten app that lets teachers record children's moods, lets parents follow them, and rewards trash sorting with points on a class leaderboard.

The source code, issues and documentation are on GitHub⁠. The API reference, with every route, field, limit and error code, is at https://docs.kibooz.syafahadyan.com⁠. The project is licensed under GPL-3.0.

Apps that call the API should read the client guide⁠ on the tokens, the device token and the rate limits.

⁠Tags

⁠About the image

• A single static Go binary on a distroless base image, about 11 to 13 MB compressed depending on the platform
• Runs as a non-root user (UID 65532) and listens on port 8080
• Built for linux/amd64 and linux/arm64, so it also runs on Apple silicon and ARM servers. Releases up to 0.3.0 are linux/amd64 only
• Has a built-in health check that calls /healthz, which answers 200 when the database is up even if Redis is down
• SQL migrations are embedded in the binary and applied on startup

⁠What it needs

• PostgreSQL 15, which is required
• Redis 7, which is optional. Without it the API still works and /healthz reports degraded
• An S3 compatible bucket for avatars and trash photos, which is optional. Uploads are off when it is not configured

⁠Quick start

The repository ships a production Compose stack with the API, PostgreSQL and Redis.

curl -O https://raw.githubusercontent.com/SyafaHadyan/kibooz-backend/main/compose.yml
curl -o .env https://raw.githubusercontent.com/SyafaHadyan/kibooz-backend/main/.env.example
# edit .env and set DB_NAME, DB_USERNAME, DB_PASSWORD, REDIS_PASSWORD, JWT_SECRET_KEY and S3_*
docker compose up -d

To run only the API against a PostgreSQL you already have, use this.

docker run -d --name kibooz-backend -p 8080:8080 \
  -e DB_HOST=your-postgres-host -e DB_NAME=kibooz -e DB_USERNAME=kibooz -e DB_PASSWORD=change-me \
  -e JWT_SECRET_KEY=at-least-32-random-characters \
  syafa/kibooz-backend:latest

⁠Configuration

Every setting is an environment variable. The main ones are below, and the full list is in the README⁠.

⁠Running it in production

Put a reverse proxy with TLS in front of the API. The API does not set Strict-Transport-Security, so enable it on the proxy. Rate limits count users and accounts and never IP addresses, so add a request limit on the proxy or CDN to protect the public auth routes from floods.