Skip to content

A box and the library

Deutsch

2. Setting up a box

2.1 What is needed

  • a Raspberry Pi with the hardware of the box (box.md, section 1) – a box that is not wired yet can be installed as well; its page answers, and the log names what is missing
  • an SD card and the Raspberry Pi Imager on the PC
  • a WLAN with internet: the installer fetches the packages of the operating system
  • the password the user admin of the page of the box shall have, at least 8 characters
  • with a library: its bootstrap password, set when the library was installed (section 3)

2.2 Writing the card

  1. In the Raspberry Pi Imager choose "Raspberry Pi OS Lite (64-bit)".
  2. In the settings of the Imager set the hostname (e.g. kitchen – the page is then https://kitchen.local), the user, the WLAN with its country, the time zone and SSH; the Imager offers "public-key authentication only".
  3. Write the card, put it into the box and switch the box on.
  4. Log in from the PC: ssh <user>@<hostname>.local.

The installer never touches what the Imager set: hostname, user, WLAN, time zone, SSH.

2.3 The installer

A box that works alone gets the installer from GitHub:

curl -fsSL https://github.com/tgd1975/tinyjukebox/releases/latest/download/install.sh | sudo bash

A box for a library gets its line from the page of the library: tab "Boxes", section "Add a box", "Copy". The line names the library and the key of its certificate, so that the box trusts exactly this library.

What happens:

  • All questions come first: the password of the user admin of the page and, with a library, the bootstrap password. They are read from the terminal, never from the command line.
  • The installer checks that it runs on Raspberry Pi OS Lite (64-bit), Debian 13. On anything else it stops before it changes something and says what it found.
  • It sets up the system, installs the box software into a slot and prints the address of the page. It restarts the box once. On a Pi 3 it takes a few minutes; nothing is compiled.
  • A box for a library registers at its first start and appears in the tab "Boxes" of the library by itself.
  • What it printed is kept in /var/log/tinyjukebox-install.log, also what happened after the restart.

Running it again is safe: it changes nothing that is right already, and it never touches albums, tags, progress, users or the link to a library. It is also the way to bring the system of a box up to date (section 4.4). There is no uninstaller: a Pi is freed by writing its card anew.

All options of the installer: deployment.md, section 5.1.

2.4 After the installation

  • The first start should happen with WLAN: the box has no clock, and the certificate of the page is created then.
  • Open the page and log in as admin. The browser warns about the certificate the first time (section 5.4).
  • Choose the language under the login, "Deutsch / English".
  • Place a tag: the LED turns yellow, and the tab "Now" offers to link it (manual, section 7.2).
  • If there are several boxes, give the box a name: tab "System", section "Library", "Rename".

For a box that was set up anew, the acceptance checklist goes through start, buttons, LED, tags and headset one by one.

2.5 With the playbook

Our own box is set up from the PC with an Ansible playbook, which runs the installer and also writes the config of the box and its users. That is the way for a developer who keeps the box in the repository: deployment.md, section 5.2.

3. The library

3.1 Where it runs

Where How Updated
Synology NAS the package tinyjukebox-library, installed in the Package Center by hand, with a newer package (section 4.3)
Docker the image ghcr.io/tgd1975/tinyjukebox (linux/amd64, linux/arm64) by pulling a newer image
PC pip install tinyjukebox, then tinyjukebox-library --data DIR with pip install --upgrade tinyjukebox

The package is built for one platform, rtd1296 – the DS418j and NAS with the same processor. Another NAS needs another build, or Docker.

3.2 On the NAS

  1. Before: install the Python 3.12 of SynoCommunity on the NAS (the package python312). Choose a bootstrap password of at least 16 characters, e.g. with openssl rand -hex 24. Every box proves it once, the first time it connects.
  2. Fetch the package (tinyjukebox-library-<version>-<build>-rtd1296.spk) from the newest release on GitHub. With a clone of the repository on the PC, ./fetch_release.sh fetches it into dist/ and checks it.
  3. Install it: Package Center of DSM, "Manual Install", choose the file, confirm the warning about packages of third parties. The dialog asks for the password of the user admin of the page (at least 8 characters) and for the bootstrap password.
  4. Check: the Package Center shows the package as running, and https://<nas>:8866 opens the page. Log in as admin. If the start failed, the reason is in var/server.log (section 7.2).
  5. Users: the library has the user admin only. Add the others on its page, tab "System", section "Users".

The package runs as a user of its own, tinyjukebox-library. DSM creates the shared folder tinyjukebox at the first start, with albums/, images/ and json/ in it; albums can also be put there with SMB or File Station, and Hyper Backup includes the folder. Certificate, users and config live in /var/packages/tinyjukebox-library/var/, which an update keeps and which DSM never removes – also not when the package is removed. To start from nothing: library.md, section 3.7.

3.3 In Docker

Two passwords as files, then compose starts a library and a box without hardware to try:

cd deploy/docker && openssl rand -hex 12 > admin-password && openssl rand -hex 24 > bootstrap-password
docker compose up -d   # https://localhost:8866/ and https://localhost:8443/, user admin, the password in admin-password

The library alone:

docker run -d --name library --restart unless-stopped -p 8866:8866 \
    -v library:/data -v /path/to/albums:/data/albums ghcr.io/tgd1975/tinyjukebox
  • Everything that must survive lies below /data: one volume, and if wanted the albums as a folder of the host. A mounted folder must be writable for the user of the image (uid 1000).
  • Without TINYJUKEBOX_ADMIN_PASSWORD the password of admin is generated and printed once: docker logs library.
  • The bootstrap password comes from TINYJUKEBOX_BOOTSTRAP_PASSWORD, or it is set in the tab "Boxes".
  • Instead of the passwords themselves, TINYJUKEBOX_ADMIN_PASSWORD_FILE and TINYJUKEBOX_BOOTSTRAP_PASSWORD_FILE name a file that holds them; a variable can be read with docker inspect.
  • A box joins with the line of the tab "Boxes". Its address must be the one of the host, not the name of the container.

More: library.md, section 3.9.

3.4 On a PC

pip install tinyjukebox
tinyjukebox-library --data ~/library        # https://localhost:8866/

Everything lies below the folder: data/, albums/, images/, ssl/, log/, backups/. At the first start it asks for the password of admin on the terminal. A computer that is switched off is no library for the boxes: they play on with what they have and deliver their changes later.

3.5 Filling it with the data of a box

The library starts empty. If a box has albums and tags already, a command on the PC brings them over. It keeps the ids, so that box and library agree from the start, and it can be repeated: what is there already is skipped.

rsync -a pi@tinyjukebox.local:/srv/tinyjukebox/json/ ~/box-copy/json/
rsync -a pi@tinyjukebox.local:/srv/tinyjukebox/albums/ ~/box-copy/albums/
tinyjukebox-fill-library https://<nas>:8866 --user admin \
    --json ~/box-copy/json --albums ~/box-copy/albums --images ~/box-copy/json/images

It asks for the password and shows the fingerprint of the certificate of the library for confirmation (section 5.4). In a clone of the repository the command is uv run tinyjukebox-fill-library …. The progress comes from the box itself with its first synchronization. A box that is simply connected to the library brings its data as well (manual, section 13.2); this command is for many albums at once.

3.6 Connecting the boxes

  • A box that runs already: on its page, tab "System", section "Library": the address and the bootstrap password (manual, section 13.2).
  • A new box: the line of the tab "Boxes", section "Add a box" (section 2.3).
  • A box that was set up again is a new box. On the page of the library, tab "Boxes", it takes over the progress and settings of the old one.

3.7 New versions for the boxes

The library fetches the versions of the box software from the releases on GitHub and hands them to its boxes. For that it needs access to the releases:

  • The repository is public: an empty file var/github-token on the NAS is enough, owned by the user tinyjukebox-library; then stop and start the package.
  • The repository is private: create a fine-grained token on GitHub for this one repository with the right "Contents: Read-only", and enter it on the page of the library, tab "Versions", section "Access to the releases". The library checks it before it keeps it and looks for a release at once.

The Docker image and tinyjukebox-library --data ask the releases of the project without a token. Which version a box gets and how it is tried: section 4.1.