Getting Started

Self-Host

Run YotoShelf on your own hardware or a VPS. A single container image, an SQLite database, and a Yoto API token are all you need.

YotoShelf ships as a single OCI container image from registry.gitlab.com/yotoshelf/yotoshelf. It embeds its own static file server and uses SQLite — there are no external databases or caches to run alongside it.

What you need

Docker (or Podman) with Compose support
A Yoto account with at least one Make Your Own card
Persistent storage for the database and card library (a Docker volume or a bind mount)
Two random secrets: YOTOSHELF_SESSION_SECRET and YOTOSHELF_ENCRYPTION_KEY (each at least 32 bytes)

Sections in this guide

Quick Start — container run command, required environment variables, first login
Build from Source — clone, toolchain setup, the just dev loop
Configuration — full environment variable reference with defaults
Backup & Restore — built-in CLI subcommands, cron scheduling, restore validation
Hardware Notes — Yoto device constraints: cover dimensions, display pixels, audio pipeline

Runtime image

The published image is built from the repository Containerfile on every push to main. It is a three-stage build: Node (frontend) → Go (binary) → Alpine (runtime + ffmpeg). The final layer is minimal — Alpine plus ffmpeg plus the single statically-compiled binary.

The image is tagged latest and by commit SHA. Pin to a SHA for production; pull latest to track the main branch.