Build from Source

Prerequisites

• mise — mise.jdx.dev installs and pins Go, Node, sqlc, and golangci-lint. Install with curl https://mise.run | sh.
• ffmpeg — required for audio transcoding. Install via brew install ffmpeg (macOS) or apt install ffmpeg (Debian/Ubuntu).

All other tools are version-pinned in .mise.toml and installed automatically when you run mise install.

Clone and start

git clone --recurse-submodules https://gitlab.com/yotoshelf/yotoshelf.git
cd yotoshelf
mise install
just dev

The --recurse-submodules flag is required. The frontend consumes frontend/design as a git submodule — a plain clone will fail at build time. If you already cloned without it, run git submodule update --init.

just dev starts the Go backend on :8080 and the Vite frontend dev server on :4300 with hot reload. Open http://localhost:4300 and log in with admin@localhost / admin.

Key just recipes

Recipe	What it does
just dev	Start backend + frontend with hot reload
just dev-fresh	Wipe the dev database and library, then start
just check	All CI gates: lint + tests + build + govulncheck + npm audit + i18n
just check-go	Go-only gates (lint, tests, govulncheck, file-size)
just check-frontend	Frontend gates (build, npm audit, i18n check)
just generate	Regenerate sqlc types + openapi-typescript (run after SQL or huma changes)
just build	Production binary at bin/yotoshelf
just e2e	Playwright end-to-end tests (builds the binary first)

Seed fixtures

To populate a running dev instance with test content, use the sibling fixtures repo:

python3 fixtures/seed.py http://localhost:4300 admin@localhost admin

The seed script adds sample cards and tracks so the UI has content to display. It requires the dev-permissive origin — YOTOSHELF_PUBLIC_URL must match the URL you pass, or must be unset (defaults to http://localhost:4321).

Production-mode dev

To run in single-binary mode (the same way the container image runs) without Docker:

just dev-prod

This builds the frontend, embeds it into the binary, and starts the server on :8080. Use this to verify production behaviour before pushing.

Building the container image

The Containerfile in the repo root builds the same image published to the registry. To build it locally:

docker build -t yotoshelf:local .

The three-stage build (Node → Go → Alpine) requires Docker BuildKit. It does not require CGO — the Go binary links against modernc.org/sqlite (pure Go).