# Quick Start

Run YotoShelf from the registry image in under five minutes.

## Pull and run

The simplest way to start is a single `docker run` command. Replace the placeholder secrets with random strings of at least 32 characters each.

```sh
docker run -d \
  --name yotoshelf \
  -p 8080:8080 \
  -v yotoshelf-db:/data \
  -e YOTOSHELF_DB_PATH=/data/yotoshelf.db \
  -e YOTOSHELF_LIBRARY_PATH=/data/library \
  -e YOTOSHELF_SESSION_SECRET=<random-32-bytes> \
  -e YOTOSHELF_ENCRYPTION_KEY=<random-32-bytes> \
  registry.gitlab.com/yotoshelf/yotoshelf:latest
```

Then open http://localhost:8080 and create your first admin account.

## Required environment variables

The following variables have no defaults and must be set before the server will start in production:

| Variable | Purpose |
|---|---|
| `YOTOSHELF_SESSION_SECRET` | Signs session cookies. At least 32 bytes. Rotate to invalidate all sessions. |
| `YOTOSHELF_ENCRYPTION_KEY` | Encrypts Yoto OAuth tokens at rest. At least 32 bytes. Changing this invalidates stored tokens. |

See [Configuration](/self-host/configuration) for the full variable reference, including database path, library path, SMTP, OIDC, and observability settings.

## Volumes and data

YotoShelf writes two kinds of data:

- **Database** — a single SQLite file at `YOTOSHELF_DB_PATH` (default: `yotoshelf.db` in the working directory). Back this up regularly.
- **Library** — audio files, cover images, and generated assets at `YOTOSHELF_LIBRARY_PATH` (default: `library/`). Can be large; put it on the storage you intend to keep.

Both paths should be on a persistent volume. A single volume mount works fine — set both variables to paths inside it.

## Creating an admin user

If local auth is enabled (the default), the server exposes a `create-admin` subcommand. Run it once before first login:

```sh
docker exec yotoshelf /yotoshelf create-admin \
  --email admin@example.com \
  --password <password> \
  --db-path /data/yotoshelf.db
```

Alternatively, configure OIDC and set `YOTOSHELF_LOCAL_AUTH_ENABLED=false`; the first OIDC user to log in is automatically promoted to admin. See [Configuration](/self-host/configuration).

## Reverse proxy

YotoShelf listens on `:8080` (configurable via `YOTOSHELF_LISTEN_ADDR`). Place it behind a reverse proxy (Caddy, nginx, Traefik) and terminate TLS there. Set `YOTOSHELF_TRUST_PROXY=true` so audit logs record real client IPs from `X-Forwarded-For`.

Set `YOTOSHELF_PUBLIC_URL` to the externally visible URL (e.g. `https://yotoshelf.example.com`) so OAuth callbacks and share links use the correct base.

## Verify the server is up

```sh
curl http://localhost:8080/healthz   # → 200 OK
curl http://localhost:8080/readyz    # → 200 OK (checks DB + OIDC + SMTP)
```