Installation

Bunkerbox runs natively on Debian 13 (trixie), 64 bit, as the systemd service bunkerbox with root privileges (needed for ZFS, Samba, NFS, user management and Docker). Docker is only used for apps, not for Bunkerbox itself.

One-command installation

As root on a freshly installed Debian:

curl -fsSL https://bunkerbox.znbw.de/install.sh | sudo bash

The script downloads the current version from the homepage, verifies the SHA256 checksum and runs deploy/install.sh from the package. The package is prebuilt; nothing is compiled on the target system.

At the end the script asks for the name and password of the first administrator (see below).

What the script sets up

• the Debian component contrib (for OpenZFS) if not active yet, as /etc/apt/sources.list.d/bunkerbox-contrib.sources
• packages: zfs-dkms, zfsutils-linux, linux-headers-<arch>, samba, nfs-kernel-server, nfs-common, cifs-utils, acl, smartmontools, lm-sensors, parted, gdisk, perl, curl
• Docker Engine and the compose plugin from Docker's Debian repository (/etc/apt/sources.list.d/docker.sources)
• Node.js 24 (NodeSource) if no suitable version is installed
• packages of the additional features (also installed on every update when missing): incus, ovmf, rsync, rclone, openssh-client, nut-server, nut-client, hdparm, e2fsprogs, openssl
• a self-signed certificate for HTTPS in /appdata/bunkerbox/data/tls/ (HTTPS is switched on under Security)
• the services smbd, nfs-server and docker (enabled and started)
• the group bunkerbox-admin and the first administrator
• the service bunkerbox (port 80)

BUNKERBOX_SKIP_ZFS=1 or BUNKERBOX_SKIP_DOCKER=1 skip ZFS or Docker.

First administrator

Administrators are Linux users in the group bunkerbox-admin. The installer creates the first one as long as none exists:

• interactive: asks for name and password on the terminal (also works with curl … | sudo bash)
• without a terminal: set BUNKERBOX_ADMIN=<name> and BUNKERBOX_ADMIN_PASSWORD=<password>

An existing Linux user is only added to the group and keeps its password. A new user gets no login shell (/usr/sbin/nologin); the password is set as Linux and as Samba password.

More administrators:

sudo /appdata/bunkerbox/app/deploy/install.sh --add-admin <name>

Layout

Path	Content
/appdata/bunkerbox/releases/<version>	installed versions (the last three are kept)
/appdata/bunkerbox/app	symlink to the active version
/appdata/bunkerbox/data	settings, sessions, feature data, credentials for remote mounts (mode 700)
/appdata/bunkerbox/bunkerbox.env	optional environment variables, e.g. PORT (mode 600)

After changing bunkerbox.env: systemctl restart bunkerbox.

Bunkerbox is reached directly, without a reverse proxy. The service starts node --require ./preload.cjs server.js; this small preload script passes the actual peer of every connection on to the application, so the login block cannot be bypassed with forged X-Forwarded-For headers. If you do put a reverse proxy in front (e.g. for HTTPS), list it in bunkerbox.env:

BUNKERBOX_TRUSTED_PROXIES=127.0.0.1, 10.0.0.0/8

Addresses and networks (IPv4 and IPv6, CIDR) are separated by commas or spaces. Only requests from these addresses may set X-Forwarded-For and X-Forwarded-Proto; the client address is the right-most X-Forwarded-For entry that is not a trusted proxy.

Bunkerbox and /appdata on ZFS

Bunkerbox itself lives in /appdata/bunkerbox – at installation time usually still on the system disk. To turn /appdata into a dataset on the apps pool later, create it under Storage → Datasets with mountpoint /appdata and "Copy existing content": Bunkerbox then first copies everything in /appdata (including its own installation) into the new dataset and only mounts it there afterwards (see Storage). At boot the service unit waits with RequiresMountsFor until /appdata/bunkerbox is mounted.

Installation from source

From a copy of the repository as root:

./deploy/install.sh

The script first builds a release package (scripts/pack-release.sh, needs Node.js) and installs it as above.

Updates and rollback: see Updates.