Native install (without Docker)

The server also installs without Docker: three Debian packages run the services as systemd units and keep the library in the Postgres of the distribution. This suits a small box that does nothing else (a mini PC, a Raspberry Pi 5, a dealer appliance). Docker stays the way for a NAS, a VPS and a host that runs other containers (Quickstart).

New in v1.1

The packages come with the first release that ships them (M76). Before that, build them from a checkout (Building the packages).

Supported systems

Debian 12, Ubuntu 24.04 and Raspberry Pi OS (Bookworm), on amd64 and arm64, with systemd. Postgres 15 or newer comes from the distribution.

What gets installed

Package	Contents
bitwerk-server	the control-server (web UI, API, player discovery, rooms), the backup units, bitwerk-backup and bitwerk-restore; pulls in bitwerk-media and Postgres
bitwerk-media	the media-service (library, uploads, scans, streams on port 8082)
bitwerk-ai	the ai-service (AI features on loopback port 8084, off until an admin turns them on); recommended, so apt installs it unless you pass --no-install-recommends

The three packages always come from the same build: bitwerk-server requires exactly its own version of the others.

Path	What
/etc/bitwerk/server.env	bootstrap settings: database, ports, music folder (mode 0640, root:hifi). Every other setting is made in the web UI
/srv/bitwerk/music	music folder (uploads/, library/), owned by the user hifi
/var/lib/hifi	setup code, HTTPS certificate, the folders the web UI shares with the backup and update units
/var/cache/hifi/covers	cover cache (rebuilt by a scan)
/var/backups/bitwerk	database backups

The services run as the system user hifi, which signs in to Postgres over its Unix socket (peer authentication, no password). The package creates the role and the database hifi; the services create the schema on their first start.

Install

curl -fsSL https://github.com/Arteiii/bitwerk/releases/latest/download/install.sh | sudo sh -s -- --native

The installer checks the machine, adds the signed bitwerk APT repository (the one the players use), asks for the music folder, installs the packages with Postgres, sets up USB drives as external libraries (External drives) and shows the address of the web UI and the setup code at the end. Options as for the Docker install: --music-dir, --read-only-music, --version, --no-drives, --yes (--help lists them).

Without the installer, with the repository already set up: sudo apt install bitwerk-server. apt then installs Postgres, creates the database, starts the services and prints the address of the web UI. The setup code for the first sign-in:

sudo cat /var/lib/hifi/setup-code

Open http://<server>:8080 (or http://<server> when port 80 is free) and continue with Set up in the browser.

Moving a Docker install over

Run the same installer with --native on the machine with the Docker install. It saves the database (a backup in the Docker format and an SQL dump in /var/backups/bitwerk), stops the containers, installs the packages of the same version, loads the library, playlists, rooms and settings into the new database and gives the music folder to the user hifi. The containers’ volumes stay until you delete them (sudo /opt/bitwerk/deploy/install.sh --uninstall --purge), so the Docker install can be started again if something goes wrong.

Not taken over: values that only lived in /opt/bitwerk/.env (an admin password hash, API tokens). The installer names them; sign in with the setup code and set them again in the web UI.

Music in a different folder

Run the installer again with --native --music-dir /path/to/music: it sets MUSIC_DIR in /etc/bitwerk/server.env, gives the folder to the user hifi and, for a folder below /home or a read-only one (--read-only-music), opens it for the media-service with a drop-in (/etc/systemd/system/bitwerk-media-service.service.d/bitwerk-music.conf).

To copy music into the folder without sudo, add yourself to the group hifi: sudo adduser $USER hifi.

Services and logs

systemctl status 'bitwerk-*'
journalctl -u bitwerk-control-server -u bitwerk-media-service -u bitwerk-ai-service -f
curl -fsS http://127.0.0.1:8080/api/health

The units restart a service that stops, with a growing delay. They are hardened: no privileges except binding ports 80 and 443 for the control-server, a read-only system, no access to devices or other users’ files. The media-service also lets the kernel refuse every write outside the music folder and the cover cache (Landlock).

Backup and restore

The package sets up the same scheduled backup as the Docker installer: every 72 hours, the newest 5 kept, the interval and Back up now in the web UI (Settings → Backups). A Back up now while another backup runs waits for it and then runs.

sudo bitwerk-backup                                   # back up now
sudo bitwerk-restore /var/backups/bitwerk/hifi-….dump # replaces the database, keeps a safety copy first (relative paths work too)

Not in the backup: the music folder and /etc/bitwerk/server.env (no secrets in it; they are in the database).

Updates

In the web UI: Settings shows new releases; Update backs up the database, installs the packages of that version from the APT repository, checks that the services answer, and goes back to the previous version with the backup if they do not (log: journalctl -u bitwerk-update).

On the command line: sudo apt update && sudo apt upgrade, or sudo sh install.sh --update (backs up first). Every way keeps the database, server.env (new keys are added, your values stay) and the music.

Uninstall

sudo apt remove bitwerk-server bitwerk-media bitwerk-ai   # stops and removes the services
sudo apt purge bitwerk-server bitwerk-media bitwerk-ai    # also server.env, setup code and cover cache

Purge keeps the database, the backups and the music. To delete the database too: sudo -u postgres dropdb hifi && sudo -u postgres dropuser hifi, or let the installer do both: install.sh --uninstall --purge (asks you to type “delete”).

Building the packages

From a checkout, on the release you install on or an older one (the binaries need its C library), or with cross, whose images have an old one (the release builds use it):

cargo install cargo-deb --locked
deploy/native/build-debs.sh                                        # this machine
deploy/native/build-debs.sh --target x86_64-unknown-linux-gnu      # amd64 with cross
deploy/native/build-debs.sh --target aarch64-unknown-linux-gnu     # arm64 with cross
sudo apt install ./bitwerk-server_*.deb ./bitwerk-media_*.deb ./bitwerk-ai_*.deb

Packages installed from files are not updated from the web UI (there is no repository to fetch a version from); install newer files the same way.