apiVersion: v1
kind: Pod
metadata:
name: paperless
labels:
app: paperless
spec:
restartPolicy: Always
containers:
- name: paperless
image: ghcr.io/paperless-ngx/paperless-ngx:latest
ports:
- hostPort: 8000
containerPort: 8000
env:
- name: PAPERLESS_REDIS
value: redis://127.0.0.1:6379
- name: PAPERLESS_DBHOST
value: 127.0.0.1
- name: PAPERLESS_DBPORT
value: '5432'
- name: PAPERLESS_DBNAME
value: paperless
- name: PAPERLESS_DBUSER
value: paperless
- name: PAPERLESS_DBPASS
value: Y9o7RiXgSYrllYaOZkLsxA
- name: PAPERLESS_ADMIN_USER
value: admin
- name: PAPERLESS_ADMIN_PASSWORD
value: Y9o7RiXgSYrllYaOZkLsxA
- name: PAPERLESS_SECRET_KEY
value: DfsEG1-q1lKbFPRHuuA0yA
volumeMounts:
- name: vol-0
mountPath: /usr/src/paperless/data
- name: vol-1
mountPath: /usr/src/paperless/media
- name: vol-2
mountPath: /usr/src/paperless/export
- name: vol-3
mountPath: /usr/src/paperless/consume
securityContext:
runAsUser: 1000
runAsGroup: 1000
- name: redis
image: docker.io/redis:7-alpine
ports:
- hostPort: 6379
containerPort: 6379
volumeMounts:
- name: vol-4
mountPath: /data
command:
- redis-server
- --appendonly
- 'yes'
- name: postgres
image: docker.io/postgres:16
ports:
- hostPort: 5432
containerPort: 5432
env:
- name: POSTGRES_USER
value: paperless
- name: POSTGRES_PASSWORD
value: Y9o7RiXgSYrllYaOZkLsxA
- name: POSTGRES_DB
value: paperless
volumeMounts:
- name: vol-5
mountPath: /var/lib/postgresql/data
volumes:
- name: vol-0
hostPath:
path: ~/paperless/data
type: DirectoryOrCreate
- name: vol-1
hostPath:
path: ~/paperless/media
type: DirectoryOrCreate
- name: vol-2
hostPath:
path: ~/paperless/export
type: DirectoryOrCreate
- name: vol-3
hostPath:
path: ~/paperless/consume
type: DirectoryOrCreate
- name: vol-4
hostPath:
path: ~/paperless/redis
type: DirectoryOrCreate
- name: vol-5
hostPath:
path: ~/paperless/db
type: DirectoryOrCreate
#!/bin/bash set -e # ── Pod erstellen ────────────────────────────────────────────────── podman pod create \ --name paperless \ -p 8000:8000 \ -p 6379:6379 \ -p 5432:5432 # ── Container: paperless ───────────────────────────────────────────── podman run -d \ --pod paperless \ --name paperless \ --restart always \ -e PAPERLESS_REDIS="redis://127.0.0.1:6379" \ -e PAPERLESS_DBHOST="127.0.0.1" \ -e PAPERLESS_DBPORT="5432" \ -e PAPERLESS_DBNAME="paperless" \ -e PAPERLESS_DBUSER="paperless" \ -e PAPERLESS_DBPASS="Y9o7RiXgSYrllYaOZkLsxA" \ -e PAPERLESS_ADMIN_USER="admin" \ -e PAPERLESS_ADMIN_PASSWORD="Y9o7RiXgSYrllYaOZkLsxA" \ -e PAPERLESS_SECRET_KEY="DfsEG1-q1lKbFPRHuuA0yA" \ -v ~/paperless/data:/usr/src/paperless/data:Z \ -v ~/paperless/media:/usr/src/paperless/media:Z \ -v ~/paperless/export:/usr/src/paperless/export:Z \ -v ~/paperless/consume:/usr/src/paperless/consume:Z \ --user 1000:1000 \ ghcr.io/paperless-ngx/paperless-ngx:latest # ── Container: redis ───────────────────────────────────────────── podman run -d \ --pod paperless \ --name redis \ --restart always \ -v ~/paperless/redis:/data:Z \ docker.io/redis:7-alpine \ redis-server --appendonly yes # ── Container: postgres ───────────────────────────────────────────── podman run -d \ --pod paperless \ --name postgres \ --restart always \ -e POSTGRES_USER="paperless" \ -e POSTGRES_PASSWORD="Y9o7RiXgSYrllYaOZkLsxA" \ -e POSTGRES_DB="paperless" \ -v ~/paperless/db:/var/lib/postgresql/data:Z \ --user 999:999 \ docker.io/postgres:16 # ── Stoppen & Aufräumen ──────────────────────────────────────────── # podman pod stop paperless # podman pod rm paperless
Prerequisites once as root
0. Install Podman
apt update && apt install -y podman
1. Create user (if not existing)
useradd -m -s /bin/bash paperless passwd paperless
2. Enable linger (service runs after reboot without login)
loginctl enable-linger paperless
Save the YAML file
mkdir -p ~/.config/containers/ # Copy the YAML above to: nano ~/.config/containers/paperless.yaml
Test the pod (without autostart)
podman play kube ~/.config/containers/paperless.yaml # Check status: podman pod ps && podman ps # Stop: podman play kube --down ~/.config/containers/paperless.yaml
Create Quadlet .kube file
Place it at ~/.config/containers/systemd/paperless.kube
mkdir -p ~/.config/containers/systemd/ cat > ~/.config/containers/systemd/paperless.kube << 'EOF' [Unit] Description=paperless Pod [Kube] Yaml=%h/.config/containers/paperless.yaml [Install] WantedBy=default.target EOF
Enable systemd service
systemctl --user daemon-reload systemctl --user enable --now paperless-pod.service
Status & Logs
systemctl --user status paperless-pod.service journalctl --user -u paperless-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/paperless.yaml # or via systemd: systemctl --user restart paperless-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 paperless-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/paperless.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 paperless-<container> /bin/sh # or bash: podman exec -it paperless-<container> /bin/bash
Follow live logs
# All containers in the pod: podman pod logs -f paperless-pod # Single container: podman logs -f paperless-<container>
Pod info & resource usage
podman pod inspect paperless-pod podman stats paperless-pod
Restart pod without data loss
podman pod restart paperless-pod # or via systemd: systemctl --user restart paperless-pod.service