apiVersion: v1
kind: Pod
metadata:
name: audiobookshelf
labels:
app: audiobookshelf
spec:
restartPolicy: Always
containers:
- name: audiobookshelf
image: ghcr.io/advplyr/audiobookshelf:latest
ports:
- hostPort: 13378
containerPort: 80
env:
- name: TZ
value: Europe/Vienna
volumeMounts:
- name: vol-0
mountPath: /config
- name: vol-1
mountPath: /metadata
- name: vol-2
mountPath: /audiobooks
- name: vol-3
mountPath: /podcasts
volumes:
- name: vol-0
persistentVolumeClaim:
claimName: audiobookshelf-config
- name: vol-1
persistentVolumeClaim:
claimName: audiobookshelf-metadata
- name: vol-2
hostPath:
path: /audiobooks
type: Directory
- name: vol-3
hostPath:
path: /podcasts
type: Directory
Prerequisites once as root
0. Install Podman
apt update && apt install -y podman
1. Create user (if not existing)
useradd -m -s /bin/bash audiobookshelf passwd audiobookshelf
2. Enable linger (service runs after reboot without login)
loginctl enable-linger audiobookshelf
Save the YAML file
mkdir -p ~/.config/containers/ # Copy the YAML above to: nano ~/.config/containers/audiobookshelf.yaml
Test the pod (without autostart)
podman play kube ~/.config/containers/audiobookshelf.yaml # Check status: podman pod ps && podman ps # Stop: podman play kube --down ~/.config/containers/audiobookshelf.yaml
Create Quadlet .kube file
Place it at ~/.config/containers/systemd/audiobookshelf.kube
mkdir -p ~/.config/containers/systemd/ cat > ~/.config/containers/systemd/audiobookshelf.kube << 'EOF' [Unit] Description=audiobookshelf Pod [Kube] Yaml=%h/.config/containers/audiobookshelf.yaml [Install] WantedBy=default.target EOF
Enable systemd service
systemctl --user daemon-reload systemctl --user enable --now audiobookshelf-pod.service
Status & Logs
systemctl --user status audiobookshelf-pod.service journalctl --user -u audiobookshelf-pod.service -f podman pod ps podman ps
Apply image updates
Pull new image versions and restart the pod:
podman pull docker.io/<image>:<tag> podman play kube --replace ~/.config/containers/audiobookshelf.yaml # or via systemd: systemctl --user restart audiobookshelf-pod.service
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 audiobookshelf-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
Automatic image updates (podman-auto-update)
Podman can automatically update images and restart the pod. Enable once:
systemctl --user start podman.socket systemctl --user daemon-reload systemctl --user enable --now podman-auto-update.timer systemctl --user status podman-auto-update.timer
Test without actually updating:
podman auto-update --dry-run
Manual update
Pull a new image version and restart the pod:
podman pull <image>:<tag> podman play kube --replace \ ~/.config/containers/audiobookshelf.yaml
Find outdated images
Check local images against the registry:
podman images --filter dangling=false podman pull --all-tags <image>
Shell into a running container
podman exec -it audiobookshelf-<container> /bin/sh # or bash: podman exec -it audiobookshelf-<container> /bin/bash
Follow live logs
# All containers in the pod: podman pod logs -f audiobookshelf-pod # Single container: podman logs -f audiobookshelf-<container>
Pod info & resource usage
podman pod inspect audiobookshelf-pod podman stats audiobookshelf-pod
Restart pod without data loss
podman pod restart audiobookshelf-pod # or via systemd: systemctl --user restart audiobookshelf-pod.service