Skip to content

Requirements

This document defines the product requirements for Snackbox. Requirements are defined according to RFC 2119.

Most CMS solutions are too heavy, too opinionated, or tied to a specific frontend. Snackbox is a minimal headless CMS that exposes a clean JSON REST API — decoupled from any frontend so teams can build on top of it freely. It is built to run as hundreds of independent, self-hosted instances with minimal operational effort. These two goals — frontend freedom and operational simplicity — drive every requirement below.

Functional Requirements

Must

  • Expose a JSON REST API for managing pages, posts, tags, users, and media files
  • Authenticate requests via JWT bearer tokens
  • Enforce role-based access control with at least two distinct roles (admin and author)
  • Support paginated list endpoints for all collection resources
  • Run as a single statically-linked binary with no external runtime dependencies
  • Run as a non-root user
  • Apply database migrations automatically on startup
  • Support graceful shutdown (drain in-flight requests before exit)

Must not

  • Require a network-accessible database (SQLite is embedded)
  • Expose the metrics endpoint on the public API port
  • Store passwords in plaintext (bcrypt or equivalent hashing required)

Quality Attributes

Should

  • Provide Prometheus-compatible metrics for HTTP traffic, auth failures, and media upload volume
  • Support configurable CORS origins, rate limits, and upload size
  • Rate-limit authentication endpoints per IP address to slow credential stuffing attacks
  • Ship with deployment artifacts for systemd and Docker
  • Comply with the 12-factor app methodology — see 12FACTOR.md for the current compliance evaluation

Should not

  • Bundle a frontend or template engine
  • Contain business logic in the router or middleware layers

Deployment Constraints

These constraints apply to all supported deployment targets.

Constraint Value
Supported platforms Linux x86-64 and arm64
Minimum RAM 64 MB (idles at ~16 MB, peaks ~26 MB under load; leaves headroom for the OS)
Public exposure Must run behind a reverse proxy (nginx, Caddy, or similar) for TLS termination; the process itself must not be exposed directly to the internet
JWT secret Minimum 32 characters; no default — the server refuses to start without it

Out of Scope

The following are explicitly out of scope for the 1.x line:

  • Frontend rendering or template engines
  • Horizontal scaling / multi-instance coordination (planned for 2.0.0 via MariaDB and Redis backends)
  • S3-compatible media storage (planned for 2.0.0)
  • Kubernetes-native deployment manifests (planned for 2.0.0, depends on MariaDB + S3 backends)
  • Scheduled or queued content publishing