BookStack
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: wEDtozgtH3kHj5Y_S3l2qg
- name: DB_DATABASE
value: bookstack
volumeMounts:
- name: vol-1
mountPath: /config
- name: mariadb
image: docker.io/mariadb:11
env:
- name: MARIADB_ROOT_PASSWORD
value: pAG46BgMUXQbblKbLie_NA
- name: MARIADB_USER
value: bookstack
- name: MARIADB_PASSWORD
value: wEDtozgtH3kHj5Y_S3l2qg
- 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
Deployment Guide rootless
Prerequisites once as root
0. Install Podman
apt update && apt install -y podman
1. Create user (if not existing)
useradd -m -s /bin/bash passwd
2. Enable linger (service runs after reboot without login)
loginctl enable-linger
Switch to deployment user
su -
Use su - with the dash — this creates a proper login shell as . Without the dash, root environment variables carry over and rootless Podman will not work correctly.
As deployment user
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
Save the YAML file
mkdir -p ~/.config/containers/ nano ~/.config/containers/bookstack.yaml
Test the pod (without autostart)
podman play kube ~/.config/containers/bookstack.yaml # Check status: podman pod ps && podman ps # Stop: podman play kube --down ~/.config/containers/bookstack.yaml
Create Quadlet .kube file
%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
Start systemd service
systemctl --user daemon-reload systemctl --user start bookstack.service
Status & Logs
systemctl --user status bookstack.service journalctl --user -u bookstack.service -f podman pod ps podman ps
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
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 is the running pod listening on?
podman port bookstack-pod
Custom DNS for the pod
Set a custom DNS server (e.g. local Pi-hole):
# In YAML under spec.dnsConfig:
spec:
dnsConfig:
nameservers:
- 192.168.1.x
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
Manual update
Pull a new image version and restart the pod:
podman pull <image>:<tag> podman play kube --replace \ ~/.config/containers/bookstack.yaml
Check for outdated images
List local images and test auto-update without applying:
podman images podman auto-update --dry-run
Shell into a running container
podman exec -it bookstack-<container> /bin/sh # or bash: podman exec -it bookstack-<container> /bin/bash
Follow live logs
# All containers in the pod: podman pod logs -f bookstack-pod # Single container: podman logs -f bookstack-<container>
Pod info & resource usage
podman pod inspect bookstack-pod podman stats bookstack-pod
Restart pod without data loss
podman pod restart bookstack-pod # or via systemd: systemctl --user restart bookstack.service
Stop & remove pod
podman pod stop bookstack-pod podman pod rm bookstack-pod
All in one
podman pod stop bookstack-pod && podman pod rm bookstack-pod
