Skip to content

Snackbox (by Cozy Badger)

A cozy home for your content - ready for any frontend.

Snackbox Hero

Pipeline Coverage Issues Release License

Motivation

Most CMS solutions are either too heavy, too opinionated, or tied to a specific frontend framework. Snackbox is a minimal, self-hosted headless CMS that exposes a clean REST API so you can build any frontend you like on top of it.

Exactly what we need for Cozy Badger, so we can deploy, publish and operate hundreds of instances with minimal operational effort.

Getting Started

The quickest way to run Snackbox locally is via Docker:

# 1. Clone the repository
git clone https://gitlab.com/cozybadgerde/applications/snackbox.git
cd snackbox

# 2. Copy and edit the example configuration
cp configs/.env.example .env
# Set at minimum: JWT_SECRET, ADMIN_EMAIL, ADMIN_PASSWORD

# 3. Start the container
docker compose -f deployments/docker/docker-compose.yml up -d

# 4. Verify it is running
curl http://localhost:8080/health

Description

Snackbox manages pages, posts, tags, users, and media files via a JSON REST API. It uses SQLite for storage and JWT for authentication, making it easy to run with zero external dependencies.

The full API is described in the OpenAPI specification on GitLab.

Features

  • Manage pages, posts, tags, users, and media files via a JSON REST API
  • JWT bearer authentication with configurable token expiry
  • SQLite storage — zero external dependencies, single file to back up
  • Role-based access control (admin / author)
  • Paginated list endpoints
  • CORS support, per-IP rate limiting on login, configurable max upload size
  • Prometheus metrics endpoint (/metrics) for HTTP traffic, auth failures, and media upload volume
  • Runs as a fully static binary — no runtime dependencies
  • Ships with a systemd service file and a Docker Compose setup for easy deployment

Administrator Manual

For installation and operating as a binary on your operating system or in containers via Docker and Kubernetes, see the Administrator Manual.

User Manual

After the initial setup, check out the User Manual.

Developer Manual

To adapt the code, learn about the architecture, or contribute, see the Developer Manual.

Issues

License

Except otherwise noted, all work is licensed under a BSD-3-Clause License.

Contact