Firefly III
Deployment rootless
1. Prepare the host
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 firefly passwd firefly
Enable linger (services keep running after logout and start after reboot)
loginctl enable-linger firefly
Switch to deployment user
su - firefly
Use su - with the dash — this creates a proper login shell as firefly. 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: firefly
labels:
app: firefly
spec:
restartPolicy: Always
containers:
- name: db
image: docker.io/postgres:16-alpine
env:
- name: POSTGRES_USER
value: firefly
- name: POSTGRES_PASSWORD
value: da-1sJAK-4m2JHwEMejZQQ
- name: POSTGRES_DB
value: firefly
- name: PGDATA
value: /var/lib/postgresql/data/pgdata
volumeMounts:
- name: vol-0
mountPath: /var/lib/postgresql/data
- name: app
image: docker.io/fireflyiii/core:latest
imagePullPolicy: Always
ports:
- containerPort: 8080
hostPort: 8080
env:
- name: APP_KEY
value: base64:CHANGEME
- name: APP_URL
value: http://localhost:8080
- name: DB_CONNECTION
value: pgsql
- name: DB_HOST
value: localhost
- name: DB_PORT
value: '5432'
- name: DB_DATABASE
value: firefly
- name: DB_USERNAME
value: firefly
- name: DB_PASSWORD
value: da-1sJAK-4m2JHwEMejZQQ
- name: TRUSTED_PROXIES
value: '**'
- name: STATIC_CRON_TOKEN
value: da-1sJAK-4m2JHwEMejZQQ
- name: TZ
value: Europe/Vienna
volumeMounts:
- name: vol-1
mountPath: /var/www/html/storage/upload
- name: cron
image: docker.io/alpine:latest
imagePullPolicy: Always
args:
- sh
- -c
- echo '0 3 * * * wget -qO- http://localhost:8080/api/v1/cron/da-1sJAK-4m2JHwEMejZQQ'
| crontab - && crond -f -L /dev/stdout
volumes:
- name: vol-0
persistentVolumeClaim:
claimName: firefly-db
- name: vol-1
persistentVolumeClaim:
claimName: firefly-upload
Save the YAML file
mkdir -p ~/.config/containers/ nano ~/.config/containers/firefly.yaml
Test the pod (without autostart)
podman kube play ~/.config/containers/firefly.yaml # Check status: podman pod ps && podman ps # Stop: podman kube down ~/.config/containers/firefly.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/firefly.yaml).service # Status & logs: systemctl --user status podman-kube@$(systemd-escape ~/.config/containers/firefly.yaml).service journalctl --user -u podman-kube@$(systemd-escape ~/.config/containers/firefly.yaml).service -f
The day-to-day commands below have a block for this service.
Create Quadlet .kube file
[Unit] Description=firefly pod After=network-online.target Wants=network-online.target [Kube] Yaml=%h/.config/containers/firefly.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/firefly.kube
Start systemd service
systemctl --user daemon-reload systemctl --user start firefly.service
Status & Logs
systemctl --user status firefly.service journalctl --user -u firefly.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
Day-to-day logs, restart, update, remove (click to open)
Logs & shell into a container
podman logs -f firefly-db podman logs -f firefly-app podman logs -f firefly-cron podman exec -it firefly-db /bin/sh
Restart
systemctl --user restart firefly.service
Update an image by hand
Pull the new version, the restart recreates the containers from it:
podman pull <image>:<tag> systemctl --user restart firefly.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 firefly.service rm ~/.config/containers/systemd/firefly.kube systemctl --user daemon-reload
podman older than 4.4 (podman-kube@ from step 3)
systemctl --user restart podman-kube@$(systemd-escape ~/.config/containers/firefly.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/firefly.yaml).service
Delete the data — permanent, only after stop & remove
podman volume rm firefly-db podman volume rm firefly-upload
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.
Save the unit files
[Unit] Description=firefly pod [Pod] PodName=firefly PublishPort=8080:8080
[Unit] Description=firefly-db container [Container] Image=docker.io/postgres:16-alpine Pod=firefly.pod ContainerName=firefly-db Environment=POSTGRES_USER=firefly Environment=POSTGRES_PASSWORD=da-1sJAK-4m2JHwEMejZQQ Environment=POSTGRES_DB=firefly Environment=PGDATA=/var/lib/postgresql/data/pgdata Volume=firefly-db:/var/lib/postgresql/data [Service] Restart=always [Install] WantedBy=default.target
[Unit] Description=firefly-app container [Container] Image=docker.io/fireflyiii/core:latest Pod=firefly.pod ContainerName=firefly-app Pull=always Environment=APP_KEY=base64:CHANGEME Environment=APP_URL=http://localhost:8080 Environment=DB_CONNECTION=pgsql Environment=DB_HOST=localhost Environment=DB_PORT=5432 Environment=DB_DATABASE=firefly Environment=DB_USERNAME=firefly Environment=DB_PASSWORD=da-1sJAK-4m2JHwEMejZQQ Environment=TRUSTED_PROXIES=** Environment=STATIC_CRON_TOKEN=da-1sJAK-4m2JHwEMejZQQ Environment=TZ=Europe/Vienna Volume=firefly-upload:/var/www/html/storage/upload [Service] Restart=always [Install] WantedBy=default.target
[Unit] Description=firefly-cron container [Container] Image=docker.io/alpine:latest Pod=firefly.pod ContainerName=firefly-cron Pull=always Exec=sh -c "echo '0 3 * * * wget -qO- http://localhost:8080/api/v1/cron/da-1sJAK-4m2JHwEMejZQQ' | crontab - && crond -f -L /dev/stdout" [Service] Restart=always [Install] WantedBy=default.target
Save all of them to ~/.config/containers/systemd/:
mkdir -p ~/.config/containers/systemd/ nano ~/.config/containers/systemd/firefly.pod nano ~/.config/containers/systemd/firefly-db.container nano ~/.config/containers/systemd/firefly-app.container nano ~/.config/containers/systemd/firefly-cron.container
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 firefly-pod.service
Status & Logs
systemctl --user status firefly-pod.service journalctl --user -u firefly-db.service -f journalctl --user -u firefly-app.service -f journalctl --user -u firefly-cron.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 firefly-db podman logs -f firefly-app podman logs -f firefly-cron podman exec -it firefly-db /bin/sh
Restart
systemctl --user restart firefly-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 firefly-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 firefly-pod.service rm ~/.config/containers/systemd/firefly.pod rm ~/.config/containers/systemd/firefly-db.container rm ~/.config/containers/systemd/firefly-app.container rm ~/.config/containers/systemd/firefly-cron.container systemctl --user daemon-reload
Delete the data — permanent, only after stop & remove
podman volume rm firefly-db podman volume rm firefly-upload
A docker-compose.yml for podman-compose. Handy if you already work with Compose; there are no per-container systemd services.
Install podman-compose as root
Run this as root, e.g. together with the prerequisites before su - firefly.
apt install -y podman-compose
Save the compose file
services:
db:
image: docker.io/postgres:16-alpine
restart: always
environment:
- POSTGRES_USER=firefly
- POSTGRES_PASSWORD=da-1sJAK-4m2JHwEMejZQQ
- POSTGRES_DB=firefly
- PGDATA=/var/lib/postgresql/data/pgdata
volumes:
- firefly-db:/var/lib/postgresql/data
ports:
- 8080:8080
app:
image: docker.io/fireflyiii/core:latest
pull_policy: always
restart: always
environment:
- APP_KEY=base64:CHANGEME
- APP_URL=http://localhost:8080
- DB_CONNECTION=pgsql
- DB_HOST=localhost
- DB_PORT=5432
- DB_DATABASE=firefly
- DB_USERNAME=firefly
- DB_PASSWORD=da-1sJAK-4m2JHwEMejZQQ
- TRUSTED_PROXIES=**
- STATIC_CRON_TOKEN=da-1sJAK-4m2JHwEMejZQQ
- TZ=Europe/Vienna
depends_on:
db:
condition: service_started
volumes:
- firefly-upload:/var/www/html/storage/upload
network_mode: service:db
cron:
image: docker.io/alpine:latest
pull_policy: always
restart: always
command:
- sh
- -c
- echo '0 3 * * * wget -qO- http://localhost:8080/api/v1/cron/da-1sJAK-4m2JHwEMejZQQ'
| crontab - && crond -f -L /dev/stdout
depends_on:
db:
condition: service_started
network_mode: service:db
volumes:
firefly-db: null
firefly-upload: null
mkdir -p ~/firefly nano ~/firefly/docker-compose.yml
Start, status & logs
cd ~/firefly podman-compose up -d podman-compose ps podman-compose logs -f # Stop: podman-compose down
Start after reboot
podman-restart.service starts every container with restart: always at boot:
systemctl --user enable podman-restart.service
Update images
cd ~/firefly 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 firefly_db_1 podman logs -f firefly_app_1 podman logs -f firefly_cron_1 podman exec -it firefly_db_1 /bin/sh
Restart
cd ~/firefly podman-compose restart
Stop & remove
cd ~/firefly podman-compose down
Delete the data — permanent, only after stop & remove
podman volume rm firefly_firefly-db podman volume rm firefly_firefly-upload
Plain podman pod create / podman create commands. Good for a quick test or to see what happens under the hood.
Save the script
#!/bin/bash set -e # ── Create named volumes ─────────────────────────────────────────── # Named volumes are created automatically — no UID/GID permission adjustment needed. podman volume exists firefly-db || podman volume create firefly-db podman volume exists firefly-upload || podman volume create firefly-upload # ── Create pod ───────────────────────────────────────────────────── podman pod create \ --name firefly \ -p 8080:8080 # ── Container: firefly-db ───────────────────────────────────────────── podman create \ --pod firefly \ --name firefly-db \ --restart always \ -e POSTGRES_USER='firefly' \ -e POSTGRES_PASSWORD='da-1sJAK-4m2JHwEMejZQQ' \ -e POSTGRES_DB='firefly' \ -e PGDATA='/var/lib/postgresql/data/pgdata' \ -v firefly-db:/var/lib/postgresql/data \ docker.io/postgres:16-alpine # ── Container: firefly-app ───────────────────────────────────────────── podman create \ --pod firefly \ --name firefly-app \ --restart always \ --pull always \ -e APP_KEY='base64:CHANGEME' \ -e APP_URL='http://localhost:8080' \ -e DB_CONNECTION='pgsql' \ -e DB_HOST='localhost' \ -e DB_PORT='5432' \ -e DB_DATABASE='firefly' \ -e DB_USERNAME='firefly' \ -e DB_PASSWORD='da-1sJAK-4m2JHwEMejZQQ' \ -e TRUSTED_PROXIES='**' \ -e STATIC_CRON_TOKEN='da-1sJAK-4m2JHwEMejZQQ' \ -e TZ='Europe/Vienna' \ -v firefly-upload:/var/www/html/storage/upload \ docker.io/fireflyiii/core:latest # ── Container: firefly-cron ───────────────────────────────────────────── podman create \ --pod firefly \ --name firefly-cron \ --restart always \ --pull always \ docker.io/alpine:latest \ sh -c 'echo '"'"'0 3 * * * wget -qO- http://localhost:8080/api/v1/cron/da-1sJAK-4m2JHwEMejZQQ'"'"' | crontab - && crond -f -L /dev/stdout' # ── Start pod ────────────────────────────────────────────────────── podman pod start firefly # ── Stop & clean up ─────────────────────────────────────────────── # podman pod stop firefly # podman pod rm firefly
nano firefly.sh
Run it, status & logs
bash firefly.sh podman pod ps && podman ps podman logs -f <container-name>
Start after reboot
podman-restart.service starts every container with --restart always at boot:
systemctl --user enable podman-restart.service
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 firefly bash firefly.sh
Day-to-day logs, restart, update, remove (click to open)
Logs & shell into a container
podman logs -f firefly-db podman logs -f firefly-app podman logs -f firefly-cron podman exec -it firefly-db /bin/sh
Restart
podman pod stop firefly podman pod start firefly
Stop & remove
podman pod rm -f firefly
Delete the data — permanent, only after stop & remove
podman volume rm firefly-db podman volume rm firefly-upload
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