BookStack

Productivity rootless 2 containers
Open in Generator
bookstack lscr.io/linuxserver/bookstack:latest · 8080:80
mariadb docker.io/mariadb:11

Deployment rootless

1. Prepare the host

Operating System:
!

Prerequisites once as root

Install Podman (needs podman 4.3 or newer; Ubuntu 22.04 ships 3.4 and is too old, use 24.04)

apt update && apt install -y podman

Create user (if not existing)

useradd -m -s /bin/bash bookstack
passwd bookstack

Enable linger (services keep running after logout and start after reboot)

loginctl enable-linger bookstack
↪

Switch to deployment user

su - bookstack

Use su - with the dash — this creates a proper login shell as bookstack. Without the dash, root environment variables carry over and rootless Podman will not work correctly.

!

Fix environment for rootless systemd (new users only — skip if already set)

Required once so systemctl --user works in non-login sessions.

cat << 'EOF' >> ~/.bashrc

# Fix for systemd user services (rootless Podman/systemctl)
export XDG_RUNTIME_DIR=/run/user/$(id -u)
export DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus
EOF
source ~/.bashrc

2. Choose a format and deploy

The same pod in four forms. Pick one and follow only its steps.

Each tab says which podman it needs. Check yours with podman --version: Debian 12 ships 4.3, Ubuntu 24.04 4.9, Debian 13 5.4, Fedora 5.8, Arch 6.x.

Kubernetes YAML for podman kube play, started by systemd through a Quadlet .kube unit (podman 4.4+; older podman like Debian 12 uses podman-kube@, see the version check below).

Kubernetes YAML 

apiVersion: v1
kind: Pod
metadata:
  name: bookstack
  labels:
    app: bookstack
spec:
  restartPolicy: Always
  containers:
  - name: bookstack
    image: lscr.io/linuxserver/bookstack:latest
    imagePullPolicy: Always
    ports:
    - containerPort: 80
      hostPort: 8080
    env:
    - name: PUID
      value: '1000'
    - name: PGID
      value: '1000'
    - name: APP_URL
      value: http://localhost:8080
    - name: DB_HOST
      value: 127.0.0.1
    - name: DB_PORT
      value: '3306'
    - name: DB_USER
      value: bookstack
    - name: DB_PASS
      value: kETXnBQHcccYrFoDxHs6Bw
    - name: DB_DATABASE
      value: bookstack
    volumeMounts:
    - name: vol-1
      mountPath: /config
  - name: mariadb
    image: docker.io/mariadb:11
    env:
    - name: MARIADB_ROOT_PASSWORD
      value: HxXbnxtHQ7a1GV21lbXREg
    - name: MARIADB_USER
      value: bookstack
    - name: MARIADB_PASSWORD
      value: kETXnBQHcccYrFoDxHs6Bw
    - name: MARIADB_DATABASE
      value: bookstack
    volumeMounts:
    - name: vol-2
      mountPath: /var/lib/mysql
    - name: vol-0
      mountPath: /docker-entrypoint-initdb.d
    securityContext:
      runAsUser: 999
      runAsGroup: 999
  initContainers:
  - name: db-init-mysql
    image: docker.io/busybox:latest
    imagePullPolicy: Always
    volumeMounts:
    - name: vol-0
      mountPath: /db-init
    command:
    - sh
    args:
    - -c
    - mkdir -p /db-init && echo LS0gQXV0by1nZW5lcmF0ZWQgYnkgcG9kbWFuLWt1YmUtZ2VuOiBleHRyYSBkYXRhYmFzZXMgZm9yIG11bHRpLWFwcCBwb2QKCkNSRUFURSBEQVRBQkFTRSBJRiBOT1QgRVhJU1RTIGBib29rc3RhY2tgOwpDUkVBVEUgVVNFUiBJRiBOT1QgRVhJU1RTICdib29rc3RhY2snQCclJyBJREVOVElGSUVEIEJZICcnOwpHUkFOVCBBTEwgUFJJVklMRUdFUyBPTiBgYm9va3N0YWNrYC4qIFRPICdib29rc3RhY2snQCclJzsKCkZMVVNIIFBSSVZJTEVHRVM7
      | base64 -d > /db-init/01-init.sql
  volumes:
  - name: vol-0
    persistentVolumeClaim:
      claimName: bookstack-db-init-mysql
  - name: vol-1
    persistentVolumeClaim:
      claimName: bookstack-config
  - name: vol-2
    persistentVolumeClaim:
      claimName: bookstack-db
1

Save the YAML file

mkdir -p ~/.config/containers/
nano ~/.config/containers/bookstack.yaml
2

Test the pod (without autostart)

podman kube play ~/.config/containers/bookstack.yaml

# Check status:
podman pod ps && podman ps

# Stop:
podman kube down ~/.config/containers/bookstack.yaml

Check your podman version

podman --version

4.4 or newer: continue with step 3 below.

Older, e.g. 4.3 on Debian 12? There is no Quadlet yet: use podman's own podman-kube@ service instead of steps 3–5 
systemctl --user enable --now podman-kube@$(systemd-escape ~/.config/containers/bookstack.yaml).service

# Status & logs:
systemctl --user status podman-kube@$(systemd-escape ~/.config/containers/bookstack.yaml).service
journalctl --user -u podman-kube@$(systemd-escape ~/.config/containers/bookstack.yaml).service -f

The day-to-day commands below have a block for this service.

3

Create Quadlet .kube file

bookstack.kube 
[Unit]
Description=bookstack pod
After=network-online.target
Wants=network-online.target

[Kube]
Yaml=%h/.config/containers/bookstack.yaml

[Service]
Restart=always

[Install]
WantedBy=default.target

%h is a systemd home-directory specifier — do not replace it with ~/.

Save to ~/.config/containers/systemd/:

mkdir -p ~/.config/containers/systemd/
nano ~/.config/containers/systemd/bookstack.kube
4

Start systemd service

systemctl --user daemon-reload
systemctl --user start bookstack.service
5

Status & Logs

systemctl --user status bookstack.service
journalctl --user -u bookstack.service -f
podman pod ps
podman ps
6

Enable automatic image updates optional

Requires AutoUpdate=registry in the .kube file. Podman then checks for new images and restarts the pod automatically:

systemctl --user enable --now podman.socket
systemctl --user daemon-reload
systemctl --user enable --now podman-auto-update.timer

# Check status:
systemctl --user status podman-auto-update.timer

# Trigger manually:
podman auto-update
Day-to-day logs, restart, update, remove (click to open)

Logs & shell into a container

podman logs -f bookstack-bookstack
podman logs -f bookstack-mariadb
podman exec -it bookstack-bookstack /bin/sh

Restart

systemctl --user restart bookstack.service

Update an image by hand

Pull the new version, the restart recreates the containers from it:

podman pull <image>:<tag>
systemctl --user restart bookstack.service

Stop & remove

Stop through systemd, otherwise Restart=always brings the pod back. To remove it for good, delete the unit files and reload:

systemctl --user stop bookstack.service
rm ~/.config/containers/systemd/bookstack.kube
systemctl --user daemon-reload

podman older than 4.4 (podman-kube@ from step 3)

systemctl --user restart podman-kube@$(systemd-escape ~/.config/containers/bookstack.yaml).service

# Update an image: pull, then restart as above
podman pull <image>:<tag>

# Stop and remove from autostart:
systemctl --user disable --now podman-kube@$(systemd-escape ~/.config/containers/bookstack.yaml).service

Delete the data — permanent, only after stop & remove

podman volume rm bookstack-config
podman volume rm bookstack-db
podman volume rm bookstack-db-init-mysql

Native systemd units without the Kubernetes YAML: one .pod plus one .container per container. Each container becomes its own systemd service (restart, logs and ordering per container). Needs podman 5.0 or newer — Debian 12 ships 4.3, use the Kube YAML tab there.

1

Save the unit files

bookstack.pod 
[Unit]
Description=bookstack pod

[Pod]
PodName=bookstack
PodmanArgs=--exit-policy=continue
PublishPort=8080:80
bookstack-db-init-mysql.container 
[Unit]
Description=bookstack-db-init-mysql container

[Container]
Image=docker.io/busybox:latest
Pod=bookstack.pod
ContainerName=bookstack-db-init-mysql
Pull=always
Volume=bookstack-db-init-mysql:/db-init
Entrypoint=sh
Exec=-c "mkdir -p /db-init && echo LS0gQXV0by1nZW5lcmF0ZWQgYnkgcG9kbWFuLWt1YmUtZ2VuOiBleHRyYSBkYXRhYmFzZXMgZm9yIG11bHRpLWFwcCBwb2QKCkNSRUFURSBEQVRBQkFTRSBJRiBOT1QgRVhJU1RTIGBib29rc3RhY2tgOwpDUkVBVEUgVVNFUiBJRiBOT1QgRVhJU1RTICdib29rc3RhY2snQCclJyBJREVOVElGSUVEIEJZICcnOwpHUkFOVCBBTEwgUFJJVklMRUdFUyBPTiBgYm9va3N0YWNrYC4qIFRPICdib29rc3RhY2snQCclJzsKCkZMVVNIIFBSSVZJTEVHRVM7 | base64 -d > /db-init/01-init.sql"

[Service]
Type=oneshot
RemainAfterExit=yes
Restart=no

[Install]
WantedBy=default.target
bookstack-bookstack.container 
[Unit]
Description=bookstack-bookstack container
Requires=bookstack-db-init-mysql.service
After=bookstack-db-init-mysql.service

[Container]
Image=lscr.io/linuxserver/bookstack:latest
Pod=bookstack.pod
ContainerName=bookstack-bookstack
Pull=always
Environment=PUID=1000
Environment=PGID=1000
Environment=APP_URL=http://localhost:8080
Environment=DB_HOST=127.0.0.1
Environment=DB_PORT=3306
Environment=DB_USER=bookstack
Environment=DB_PASS=kETXnBQHcccYrFoDxHs6Bw
Environment=DB_DATABASE=bookstack
Volume=bookstack-config:/config:Z

[Service]
Restart=always

[Install]
WantedBy=default.target
bookstack-mariadb.container 
[Unit]
Description=bookstack-mariadb container
Requires=bookstack-db-init-mysql.service
After=bookstack-db-init-mysql.service

[Container]
Image=docker.io/mariadb:11
Pod=bookstack.pod
ContainerName=bookstack-mariadb
Environment=MARIADB_ROOT_PASSWORD=HxXbnxtHQ7a1GV21lbXREg
Environment=MARIADB_USER=bookstack
Environment=MARIADB_PASSWORD=kETXnBQHcccYrFoDxHs6Bw
Environment=MARIADB_DATABASE=bookstack
Volume=bookstack-db:/var/lib/mysql:Z
Volume=bookstack-db-init-mysql:/docker-entrypoint-initdb.d
User=999
Group=999

[Service]
Restart=always

[Install]
WantedBy=default.target

Save all of them to ~/.config/containers/systemd/:

mkdir -p ~/.config/containers/systemd/
nano ~/.config/containers/systemd/bookstack.pod
nano ~/.config/containers/systemd/bookstack-db-init-mysql.container
nano ~/.config/containers/systemd/bookstack-bookstack.container
nano ~/.config/containers/systemd/bookstack-mariadb.container
2

Start the pod

The pod service pulls in every container service. Autostart at boot comes from the [Install] section of the units, no enable needed.

systemctl --user daemon-reload
systemctl --user start bookstack-pod.service
3

Status & Logs

systemctl --user status bookstack-pod.service
journalctl --user -u bookstack-db-init-mysql.service -f
journalctl --user -u bookstack-bookstack.service -f
journalctl --user -u bookstack-mariadb.service -f
podman pod ps && podman ps
Day-to-day logs, restart, update, remove (click to open)

Logs & shell into a container

podman logs -f bookstack-bookstack
podman logs -f bookstack-mariadb
podman exec -it bookstack-bookstack /bin/sh

Restart

systemctl --user restart bookstack-pod.service

Update an image by hand

Pull the new version, the restart recreates the containers from it:

podman pull <image>:<tag>
systemctl --user restart bookstack-pod.service

Stop & remove

Stop through systemd, otherwise Restart=always brings the pod back. To remove it for good, delete the unit files and reload:

systemctl --user stop bookstack-pod.service
rm ~/.config/containers/systemd/bookstack.pod
rm ~/.config/containers/systemd/bookstack-db-init-mysql.container
rm ~/.config/containers/systemd/bookstack-bookstack.container
rm ~/.config/containers/systemd/bookstack-mariadb.container
systemctl --user daemon-reload

Delete the data — permanent, only after stop & remove

podman volume rm bookstack-config
podman volume rm bookstack-db
podman volume rm bookstack-db-init-mysql

A docker-compose.yml for podman-compose. Handy if you already work with Compose; there are no per-container systemd services.

1

Install podman-compose as root

Run this as root, e.g. together with the prerequisites before su - bookstack.

apt install -y podman-compose
2

Save the compose file

docker-compose.yml 
services:
  db-init-mysql:
    image: docker.io/busybox:latest
    pull_policy: always
    restart: 'no'
    entrypoint:
    - sh
    command:
    - -c
    - mkdir -p /db-init && echo LS0gQXV0by1nZW5lcmF0ZWQgYnkgcG9kbWFuLWt1YmUtZ2VuOiBleHRyYSBkYXRhYmFzZXMgZm9yIG11bHRpLWFwcCBwb2QKCkNSRUFURSBEQVRBQkFTRSBJRiBOT1QgRVhJU1RTIGBib29rc3RhY2tgOwpDUkVBVEUgVVNFUiBJRiBOT1QgRVhJU1RTICdib29rc3RhY2snQCclJyBJREVOVElGSUVEIEJZICcnOwpHUkFOVCBBTEwgUFJJVklMRUdFUyBPTiBgYm9va3N0YWNrYC4qIFRPICdib29rc3RhY2snQCclJzsKCkZMVVNIIFBSSVZJTEVHRVM7
      | base64 -d > /db-init/01-init.sql
    volumes:
    - bookstack-db-init-mysql:/db-init
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    pull_policy: always
    restart: always
    environment:
    - PUID=1000
    - PGID=1000
    - APP_URL=http://localhost:8080
    - DB_HOST=127.0.0.1
    - DB_PORT=3306
    - DB_USER=bookstack
    - DB_PASS=kETXnBQHcccYrFoDxHs6Bw
    - DB_DATABASE=bookstack
    depends_on:
      db-init-mysql:
        condition: service_completed_successfully
      mariadb:
        condition: service_started
    volumes:
    - bookstack-config:/config:Z
    network_mode: service:mariadb
  mariadb:
    image: docker.io/mariadb:11
    restart: always
    environment:
    - MARIADB_ROOT_PASSWORD=HxXbnxtHQ7a1GV21lbXREg
    - MARIADB_USER=bookstack
    - MARIADB_PASSWORD=kETXnBQHcccYrFoDxHs6Bw
    - MARIADB_DATABASE=bookstack
    user: 999:999
    depends_on:
      db-init-mysql:
        condition: service_completed_successfully
    volumes:
    - bookstack-db:/var/lib/mysql:Z
    - bookstack-db-init-mysql:/docker-entrypoint-initdb.d
    ports:
    - 8080:80
volumes:
  bookstack-db-init-mysql: null
  bookstack-config: null
  bookstack-db: null

mkdir -p ~/bookstack
nano ~/bookstack/docker-compose.yml
3

Start, status & logs

cd ~/bookstack
podman-compose up -d
podman-compose ps
podman-compose logs -f

# Stop:
podman-compose down
4

Start after reboot

podman-restart.service starts every container with restart: always at boot:

systemctl --user enable podman-restart.service
5

Update images

cd ~/bookstack
podman-compose pull
podman-compose up -d
Day-to-day logs, restart, update, remove (click to open)

Logs & shell into a container

podman logs -f bookstack_bookstack_1
podman logs -f bookstack_mariadb_1
podman exec -it bookstack_bookstack_1 /bin/sh

Restart

cd ~/bookstack
podman-compose restart

Stop & remove

cd ~/bookstack
podman-compose down

Delete the data — permanent, only after stop & remove

podman volume rm bookstack_bookstack-config
podman volume rm bookstack_bookstack-db
podman volume rm bookstack_bookstack-db-init-mysql

Plain podman pod create / podman create commands. Good for a quick test or to see what happens under the hood.

1

Save the script

bookstack.sh 
#!/bin/bash
set -e

# ── Create named volumes ───────────────────────────────────────────
# Named volumes are created automatically — no UID/GID permission adjustment needed.
podman volume exists bookstack-db-init-mysql || podman volume create bookstack-db-init-mysql
podman volume exists bookstack-config || podman volume create bookstack-config
podman volume exists bookstack-db || podman volume create bookstack-db

# ── Create pod ─────────────────────────────────────────────────────
podman pod create \
  --name bookstack \
  -p 8080:80

# ── Init container: bookstack-db-init-mysql ────────────────────────────────────────
podman create \
  --pod bookstack \
  --name bookstack-db-init-mysql \
  --init-ctr=once \
  --pull always \
  -v bookstack-db-init-mysql:/db-init \
  --entrypoint sh \
  docker.io/busybox:latest \
  -c 'mkdir -p /db-init && echo LS0gQXV0by1nZW5lcmF0ZWQgYnkgcG9kbWFuLWt1YmUtZ2VuOiBleHRyYSBkYXRhYmFzZXMgZm9yIG11bHRpLWFwcCBwb2QKCkNSRUFURSBEQVRBQkFTRSBJRiBOT1QgRVhJU1RTIGBib29rc3RhY2tgOwpDUkVBVEUgVVNFUiBJRiBOT1QgRVhJU1RTICdib29rc3RhY2snQCclJyBJREVOVElGSUVEIEJZICcnOwpHUkFOVCBBTEwgUFJJVklMRUdFUyBPTiBgYm9va3N0YWNrYC4qIFRPICdib29rc3RhY2snQCclJzsKCkZMVVNIIFBSSVZJTEVHRVM7 | base64 -d > /db-init/01-init.sql'

# ── Container: bookstack-bookstack ─────────────────────────────────────────────
podman create \
  --pod bookstack \
  --name bookstack-bookstack \
  --restart always \
  --pull always \
  -e PUID='1000' \
  -e PGID='1000' \
  -e APP_URL='http://localhost:8080' \
  -e DB_HOST='127.0.0.1' \
  -e DB_PORT='3306' \
  -e DB_USER='bookstack' \
  -e DB_PASS='kETXnBQHcccYrFoDxHs6Bw' \
  -e DB_DATABASE='bookstack' \
  -v bookstack-config:/config:Z \
  lscr.io/linuxserver/bookstack:latest

# ── Container: bookstack-mariadb ─────────────────────────────────────────────
podman create \
  --pod bookstack \
  --name bookstack-mariadb \
  --restart always \
  -e MARIADB_ROOT_PASSWORD='HxXbnxtHQ7a1GV21lbXREg' \
  -e MARIADB_USER='bookstack' \
  -e MARIADB_PASSWORD='kETXnBQHcccYrFoDxHs6Bw' \
  -e MARIADB_DATABASE='bookstack' \
  -v bookstack-db:/var/lib/mysql:Z \
  -v bookstack-db-init-mysql:/docker-entrypoint-initdb.d \
  --user 999:999 \
  docker.io/mariadb:11

# ── Start pod ──────────────────────────────────────────────────────
podman pod start bookstack

# ── Stop & clean up ───────────────────────────────────────────────
# podman pod stop bookstack
# podman pod rm bookstack
nano bookstack.sh
2

Run it, status & logs

bash bookstack.sh
podman pod ps && podman ps
podman logs -f <container-name>
3

Start after reboot

podman-restart.service starts every container with --restart always at boot:

systemctl --user enable podman-restart.service
4

Remove or rebuild

The script creates the pod once. To apply changes or new images, remove the pod and run the script again (named volumes stay):

podman pod rm -f bookstack
bash bookstack.sh
Day-to-day logs, restart, update, remove (click to open)

Logs & shell into a container

podman logs -f bookstack-bookstack
podman logs -f bookstack-mariadb
podman exec -it bookstack-bookstack /bin/sh

Restart

podman pod stop bookstack
podman pod start bookstack

Stop & remove

podman pod rm -f bookstack

Delete the data — permanent, only after stop & remove

podman volume rm bookstack-config
podman volume rm bookstack-db
podman volume rm bookstack-db-init-mysql
Useful Tips

Ports < 1024 (e.g. 80, 443)

Rootless cannot open privileged ports. Solution:

sysctl net.ipv4.ip_unprivileged_port_start=80

Make persistent in /etc/sysctl.d/99-podman.conf.

Containers communicate via localhost

All containers in the pod share the same network namespace. Always use localhost, not container names.

# Correct (e.g. app → db):
localhost:5432

# Wrong (doesn't work in a pod):
db-container:5432

List open ports

Which ports are the running containers publishing? See the PORTS column:

podman ps

Custom DNS for the pod

Set a custom DNS server (e.g. local Pi-hole) in the generator under DNS server. Every format picks it up.

Set volume ownership

Fix permission errors by adjusting UID/GID in the user namespace:

podman unshare chown 1000:1000 /path/to/volume

SELinux volume labels

On SELinux systems (RHEL, Fedora) set the volume suffix:

/host/path:/container/path:Z   # private
/host/path:/container/path:z   # shared

List all volumes

podman volume ls
podman volume inspect <volume-name>

Volume backup

Back up data from a named volume:

podman run --rm \
  -v <volume-name>:/data:ro \
  -v $(pwd):/backup \
  busybox tar czf /backup/backup.tar.gz /data

Cleanup

Remove unused images, containers and volumes:

podman system prune -f        # containers + images
podman image prune -f         # untagged images only
podman volume prune -f        # unused volumes

Check for outdated images

List local images; auto-update only covers units with AutoUpdate= (Kube and Quadlet tabs):

podman images
podman auto-update --dry-run

All containers, including stopped ones

podman pod ps
podman ps -a

Resource usage

podman stats --no-stream
Customize this stack
Change ports, volumes, environment variables and more in the generator.
Open in Generator