Tiny Jukebox – administration

For the person who sets up and runs the boxes and the library at home: with a terminal, a NAS or a PC, and a browser. What to do, in steps, and what happens then. How the box is operated and what the web page offers is in the manual; this document points to it instead of repeating it. Every detail – every command, every option, every file – is in the developer documents (docs/developer/, in English).

Contents:

1. Overview
2. Setting up a box
3. The library
4. Updates
5. Users and access
6. Data and backups
7. Logs and diagnostics
8. Configuration
9. If something does not work

1. Overview

1.1 What runs where

A box works alone. With a library the boxes share albums, tags, stations and covers, and the library keeps the progress of every box (manual, section 13). A box without a library fetches new versions of its software from GitHub; a box with a library fetches them from the library.

1.2 Roles

• admin may do everything: albums, tags, stations, users, backups, versions.
• user may operate the box – status, player, volume, buttons – and change the own password; on the library also make a tag known by scanning it.

A box and the library each have their own users. Users and passwords on the page: manual, section 11.

1.3 The files of a box

All of it belongs to the user of the box, pi on our box. The complete list: box.md, section 6.

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

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.

4. Updates

4.1 The box software

A box installs new versions by itself: with a library from the library, without one from GitHub. A new version starts the next time the box is switched on, on probation. If it does not work – it does not start, or it fails its first seconds – the box starts the version before after a few seconds by itself. A version stays on probation until a tag was placed and an album played because of it.

• Without a library the box looks once a day for a new release and installs it after a waiting time of three days; a correction in that time replaces it before any box got it.
• With a library a box gets a new version at once. In the tab "Versions" of the library every version has a state: use (boxes install it by themselves), manual (by hand only), dontuse (every box leaves it at once).
• The update mode of a box – "automatic", "by hand only" ("ask" without a library) or "off" – is set on its page, tab "System", section "Version" (manual, section 13.4).

On the box the same is a command. It runs as the user of the box, never with sudo:

tinyjukebox-slot status           # the versions on the box, the one that runs, the mode, the last switches
tinyjukebox-slot check            # what the library offers - without a library: GitHub
tinyjukebox-slot update --now     # the newest permitted version, at once
tinyjukebox-slot update 0.45.0    # exactly this version
tinyjukebox-slot mode manual      # automatic, manual or off

Every call: library.md, section 6.8.

4.2 Going back to the version before

A step back takes effect at once, also while something is playing. No box installs the version that was left by itself any more.

revert switches to the other slot, whatever it holds. After a failed probation that may be the version that failed: look first with tinyjukebox-slot status. If no version starts any more, the box is in emergency mode (manual, section 13.4; library.md, section 6.10).

4.3 The library

The library never updates itself.

• On the NAS: install the newer package the same way, Package Center, "Manual Install" – without the dialog; the data stays. From a clone of the repository on the PC, ./update_library.sh <nas> does it: it fetches the package of the newest release and asks for user and password of DSM, which it does not store – or takes NAS, user and password from the vault of the playbook (library.md, section 3.7).
• In Docker: its page shows that a newer version exists. Pull the newer image and start the container again; with compose docker compose pull, then docker compose up -d.
• On a PC: pip install --upgrade tinyjukebox, then start the library again.

A library that is older than the version of a box makes the box stop: the LED changes between red, white, magenta and yellow, and the box plays nothing. Then update the library first.

4.4 The operating system of the box

The box never updates its operating system by itself. By hand, now and then:

sudo apt update && sudo apt full-upgrade

After an upgrade of Python, ALSA or BlueZ, run the installer line again (section 2.3) – on a box of the playbook ./update_box.sh – and check sound, buttons and headset. A version that needs a newer setup of the system says so on the page of the box: then the installer has to run again as well.

5. Users and access

5.1 Users from the command line

On the page an admin adds and removes users and sets passwords (manual, section 11). On the box, as the user of the box:

tinyjukebox-users -f /srv/tinyjukebox/ssl/users.yaml list
tinyjukebox-users -f /srv/tinyjukebox/ssl/users.yaml add NAME --role admin
tinyjukebox-users -f /srv/tinyjukebox/ssl/users.yaml passwd NAME
tinyjukebox-users -f /srv/tinyjukebox/ssl/users.yaml role NAME admin
tinyjukebox-users -f /srv/tinyjukebox/ssl/users.yaml remove NAME

• Only here can a role be changed. The command removes neither the last admin nor makes them a user.
• A change takes effect at once, without a restart. A new password ends the other sessions of that user.
• For a library on a PC the file is ssl/users.yaml in its folder. In Docker the image runs the command, with the volume of the library: docker run --rm -v library:/data ghcr.io/tgd1975/tinyjukebox tinyjukebox-users -f /data/ssl/users.yaml list.
• The package on the NAS has no command tinyjukebox-users: the call with the Python of the package is in operations.md, section 4.

5.2 A forgotten password

1. Another admin sets a new password on the page, tab "System", section "Users".
2. If no admin knows a password any more: log in on the box with SSH.
3. tinyjukebox-users -f /srv/tinyjukebox/ssl/users.yaml passwd admin – it asks for the new password twice.
4. Log in on the page with it.

5.3 SSH

The box is reached with ssh <user>@<hostname>.local, as the Imager set it up. If the name is not found, the address of the box in the router helps. A card that was written anew has a new key: if the PC still knows the old one, SSH refuses until the old entry is removed with ssh-keygen -R <hostname>.local.

5.4 The certificate of the page

Box and library make their own certificate, at their first start. The browser warns about it the first time.

• Compare the fingerprint the browser shows with the one in the log: the box writes it when the page starts (rest api listening on … fingerprint), the library into its log as well.
• Or import the certificate of the box as trusted: /srv/tinyjukebox/ssl/tinyjukebox.crt.
• The commands on the PC, tinyjukebox-backup and tinyjukebox-fill-library, show the fingerprint too and ask before they go on.

6. Data and backups

6.1 What a backup holds

A backup is one file with the data of a box or of the library, made while it runs:

• a box: tags, albums, stations and entries of Spotify, progress, volume limits and the covers
• the library: the catalog, the progress and settings of every box, the statistics, the states of the versions and the covers
• with "MP3s" also the albums – the file is then as large as all albums together

A box with a library needs no backup of its own: the library has everything, and a box that is set up again fetches it from there.

6.2 Making backups

Two schedules, one without and one with the albums, with their folder and how many are kept: manual, section 11.2. The backups of a box lie on its SD card: against a broken card only a backup helps that was fetched from it.

6.3 Putting a backup back

On the page, tab "System", card "Backup", "Put a backup back" – or tinyjukebox-backup … --restore FILE on the PC. The page asks once, then the box or the library starts again with the data of the backup (manual, section 11.3).

• A backup without the albums leaves the albums folder alone. Albums the data names but whose folder is missing are listed after the restore.
• On a box with a library the library wins at the next synchronization. A restore is meant for a box without a library and for the library.
• The library on another NAS, or by hand without the program: operations.md, section 10.3.

6.4 What no backup holds

• users, passwords, the certificate, tokens – in the library also settings.json with the bootstrap password
• the key of the box and its link to the library
• the key, the player and the login of Spotify: the key is pasted again, the box fetches the player again and is connected again ("Connect")
• the config file

7. Logs and diagnostics

7.1 The logs of a box

The service itself: sudo systemctl status tinyjukebox, sudo systemctl restart tinyjukebox. After a crash systemd starts it again by itself.

7.2 The logs of the library

The tab "Log" of the library helps when a box is not at hand: the boxes send their warnings and errors to the library, without passwords, keys or tag UIDs. A box that cannot start reports that too; the tab "Boxes" then shows "cannot start since …" (library.md, section 4.22).

7.3 More detail in the log

The box logs at the level INFO. For a search, set it to DEBUG:

1. A box of the installer has no config file of its own. Copy the one of its slot first: cp /srv/tinyjukebox/current/config/tinyjukebox.yaml /srv/tinyjukebox/config/.
2. In /srv/tinyjukebox/config/tinyjukebox.yaml set log-level: DEBUG.
3. sudo systemctl restart tinyjukebox.
4. After the search, remove the copy again and restart the service: from then on the file would be the config of every version, also of every later one.

7.4 Buttons, LED and reader

The tab "System" has the card "Hardware" for admins: what the drivers say about the buttons, the LED and the RFID reader, twice a second. If a button has no effect, it shows whether the button arrives at the box at all. Checking the hardware by hand on the console: operations.md, section 9.2.

8. Configuration

8.1 Where the file is

Most of what an admin sets is on the page and needs no file: volume limits (manual, section 10), the library of a box, update mode, backups. A change of the file takes effect after sudo systemctl restart tinyjukebox.

8.2 Keys an admin changes

Every key: configuration.md, sections 4 to 6, and on the documentation site the generated table of all keys (tab "Reference", "Configuration keys"). Unknown keys stop the start: the message names the path of the key.

9. If something does not work

The manual lists what a user can do (manual, section 12). For an admin:

More symptoms, with the lines of the log: operations.md, section 9.3.