Apps

Apps are Docker compose stacks. Every app is a directory /appdata/<name>/ with a compose file (docker-compose.yml, compose.yaml, compose.yml or docker-compose.yaml) and a .env file. The directory name is also the compose project name, so stacks you started by hand with docker compose up -d in that directory behave exactly like stacks created in the interface.

Requirements

• Docker Engine and the compose plugin from Docker's Debian repository (set up by the installer).
• /appdata should be a ZFS dataset on the apps pool, e.g. apps/appdata with mountpoint /appdata. If /appdata is not on ZFS, everything ends up on the system disk; the interface points this out. Because /appdata already contains the Bunkerbox installation, the dataset is created with "Copy existing content", see Storage.
• Compose and .env files are only read and written as regular files, never through symbolic links: containers that mount their stack directory could otherwise make Bunkerbox overwrite host files through a link. A link in that place is refused with an error.
• The directory /appdata/bunkerbox belongs to Bunkerbox itself and is never shown as an app.

The top of the Apps page shows whether Docker is installed and running, the Docker and compose versions and the dataset of /appdata.

Overview

The list shows every app with its status, running containers and published ports:

Status	Meaning
Running	all containers are running
Partially running	some of the containers are running
Stopped	no containers, or all of them exited
Error	a container keeps restarting, is dead or reports unhealthy
Unknown	Docker is not running

The page refreshes automatically (every 10 s, every 2 s while an operation runs).

Actions

Action	Command
Start	docker compose up --detach --remove-orphans
Stop	docker compose down --remove-orphans
Restart	docker compose restart
Update	docker compose pull, then up --detach --remove-orphans (recreates changed containers)

Actions run in the background. Their output appears live under Last operation. Each app runs at most one operation at a time; while one runs, further actions, saving and deleting are locked, and Bunkerbox updates are refused.

Creating and editing an app

New app opens the editor:

• Name: lowercase letters, digits, - and _, at most 64 characters. bunkerbox, docker, summary, validate, operations, new and catalog are reserved.
• Compose file: new apps get docker-compose.yml. Relative paths such as ./data point into the app directory.
• Environment (.env): either as a key/value table or as text. The table keeps comments and order; lines that are not valid assignments stay unchanged in the text. The .env file is stored with mode 600 (readable by root only).
• Start after creating: runs up right away.

Validate runs docker compose config on the unsaved content. Errors are shown with compose's original message. The check also points out risky settings:

• privileged: true, network_mode: host, pid: host
• a mounted Docker socket (/var/run/docker.sock), which means root access to the host
• mounted system paths such as /, /etc, /root, /boot, /usr, /proc, /sys, /var/lib/docker or /appdata/bunkerbox
• warnings from compose, e.g. variables that are not set

Saving only happens when the check passes without errors. Changes take effect after Restart or Update. Compose files may be at most 256 KiB, .env files at most 64 KiB.

Logs

The Logs tab shows docker compose logs with timestamps, for all services or one, with 100 to 5000 lines. With Follow the page fetches only the new lines every 2 s.

Deleting an app

Delete app requires typing the app name and runs docker compose down --remove-orphans. Optionally:

• Also delete named Docker volumes (--volumes).
• Also delete the directory: removes /appdata/<name> with all data. If the directory is a separate file system (e.g. its own dataset) or a symbolic link, deletion is refused; delete a dataset in Storage.

Without these options the directory and its data are kept. Deleted data can only be restored from a snapshot.

Mock mode

With BUNKERBOX_MOCK=1 Bunkerbox simulates five apps on the dataset apps/appdata: Jellyfin, Nextcloud (app, MariaDB, Redis), Paperless (one container exited), Home Assistant (host network) and Vaultwarden (stopped). Actions, validation and logs are simulated; nothing on the machine is changed.