Developing

Developing

Building TinyIce from source and contributing changes. For how the system fits together, read Architecture first.

Prerequisites

• Go 1.25+ (the module targets 1.25.x).
• Node.js 20+ — only needed to rebuild the frontend assets.

Build

git clone https://github.com/DatanoiseTV/tinyice.git
cd tinyice
make build        # frontend (go generate) + Go binary -> ./tinyice

Target	Does
make build	Rebuild frontend, then compile the binary.
make generate	Frontend assets only (go generate ./server/...).
make quick	Go binary only — reuse the existing dist/.
make dev	Vite dev server with hot reload (server/frontend).
make clean	Remove ./tinyice and server/frontend/dist.

A clean run from scratch:

rm -f tinyice.json history.db && go run .

(tinyice.json and history.db are local state; deleting them resets you to a fresh first-run. Don't delete anything else to "clean" a build — only those two plus dist/ are generated.)

Frontend

The admin UI and player are Preact + @preact/signals + Vite, in server/frontend/src/. go generate builds them and the output is embedded into the Go binary via go:embed, so the released binary is self-contained — no external CDNs, no separate asset server.

Heavy dependencies are lazy-loaded as route chunks (hls.js, DOMPurify, maplibre-gl) so audio-only pages don't pay for video/map JS. Keep that discipline: don't pull a large library onto the landing/audio path.

Conventions

These are load-bearing — most exist because breaking them caused a real incident (see the changelog):

• Stay CGO-free. Pure-Go everything (SQLite, codecs). Don't add a dependency that needs a C toolchain — it breaks single-binary cross-compilation.
• Don't embed external CDNs. Frontend assets must be self-contained.
• Respect the lock discipline in Architecture: never hold a lock across blocking I/O, no recursive RLock, parsers always advance, deadlines on hijacked reads.
• Auth-gate new endpoints by analogue. A new mutating/ingest handler inherits the auth + CSRF + role checks of its nearest sibling; shell-executing features (song_command-style) are superadmin-only.
• Tests live with the behaviour they cover. Update them in the same change.

Project docs

File	Covers
README.md	Feature tour, quick start.
ARCHITECTURE.md	Internals (this wiki's Architecture is the current synthesis).
CHANGELOG.md	Per-release history, including the failure modes behind each fix.
SECURITY.md	Disclosure process, supported versions.
docs/superpowers/	Design specs and implementation plans for major features.

Versioning and releases

TinyIce follows Semantic Versioning with annotated git tags and a Keep a Changelog CHANGELOG.md. Releases attach raw binaries plus .deb/.rpm packages and push multi-arch Docker images to GHCR; CI smoke-tests the amd64 .deb (install → file/user checks → unit-is-masked → remove) on every tag.

Filing issues and PRs

Use the issue templates for bugs and feature requests. For anything security-sensitive, don't open a public issue — follow the disclosure process.

---

Next: Architecture · Command Line and Signals · Troubleshooting and FAQ