Nginx + App + PostgreSQL
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 webapp passwd webapp
Enable linger (services keep running after logout and start after reboot)
loginctl enable-linger webapp
Switch to deployment user
su - webapp
Use su - with the dash — this creates a proper login shell as webapp. 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: webapp
labels:
app: webapp
spec:
restartPolicy: Always
containers:
- name: nginx
image: docker.io/nginx:stable
ports:
- containerPort: 80
hostPort: 8080
volumeMounts:
- name: vol-0
mountPath: /etc/nginx/conf.d
- name: app
image: docker.io/python:3.12-slim
ports:
- containerPort: 8000
hostPort: 8000
env:
- name: DATABASE_URL
value: postgresql://appuser:IR6X4_ensgm5EclNYQ9kkQ@127.0.0.1:5432/appdb
volumeMounts:
- name: vol-1
mountPath: /app
command:
- python
- -m
- http.server
- '8000'
- --directory
- /app
- name: postgres
image: docker.io/postgres:16
env:
- name: POSTGRES_USER
value: appuser
- name: POSTGRES_PASSWORD
value: IR6X4_ensgm5EclNYQ9kkQ
- name: POSTGRES_DB
value: appdb
volumeMounts:
- name: vol-2
mountPath: /var/lib/postgresql/data
securityContext:
runAsUser: 999
runAsGroup: 999
volumes:
- name: vol-0
persistentVolumeClaim:
claimName: webapp-nginx
- name: vol-1
persistentVolumeClaim:
claimName: webapp-app
- name: vol-2
persistentVolumeClaim:
claimName: webapp-db
Save the YAML file
mkdir -p ~/.config/containers/ nano ~/.config/containers/webapp.yaml
Test the pod (without autostart)
podman kube play ~/.config/containers/webapp.yaml # Check status: podman pod ps && podman ps # Stop: podman kube down ~/.config/containers/webapp.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/webapp.yaml).service # Status & logs: systemctl --user status podman-kube@$(systemd-escape ~/.config/containers/webapp.yaml).service journalctl --user -u podman-kube@$(systemd-escape ~/.config/containers/webapp.yaml).service -f
The day-to-day commands below have a block for this service.
Create Quadlet .kube file
[Unit] Description=webapp pod After=network-online.target Wants=network-online.target [Kube] Yaml=%h/.config/containers/webapp.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/webapp.kube
Start systemd service
systemctl --user daemon-reload systemctl --user start webapp.service
Status & Logs
systemctl --user status webapp.service journalctl --user -u webapp.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 webapp-nginx podman logs -f webapp-app podman logs -f webapp-postgres podman exec -it webapp-nginx /bin/sh
Restart
systemctl --user restart webapp.service
Update an image by hand
Pull the new version, the restart recreates the containers from it:
podman pull <image>:<tag> systemctl --user restart webapp.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 webapp.service rm ~/.config/containers/systemd/webapp.kube systemctl --user daemon-reload
podman older than 4.4 (podman-kube@ from step 3)
systemctl --user restart podman-kube@$(systemd-escape ~/.config/containers/webapp.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/webapp.yaml).service
Delete the data — permanent, only after stop & remove
podman volume rm webapp-nginx podman volume rm webapp-app podman volume rm webapp-db
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=webapp pod [Pod] PodName=webapp PublishPort=8080:80 PublishPort=8000:8000
[Unit] Description=webapp-nginx container [Container] Image=docker.io/nginx:stable Pod=webapp.pod ContainerName=webapp-nginx Volume=webapp-nginx:/etc/nginx/conf.d:Z [Service] Restart=always [Install] WantedBy=default.target
[Unit] Description=webapp-app container [Container] Image=docker.io/python:3.12-slim Pod=webapp.pod ContainerName=webapp-app Environment=DATABASE_URL=postgresql://appuser:IR6X4_ensgm5EclNYQ9kkQ@127.0.0.1:5432/appdb Volume=webapp-app:/app:Z Entrypoint=python Exec=-m http.server 8000 --directory /app [Service] Restart=always [Install] WantedBy=default.target
[Unit] Description=webapp-postgres container [Container] Image=docker.io/postgres:16 Pod=webapp.pod ContainerName=webapp-postgres Environment=POSTGRES_USER=appuser Environment=POSTGRES_PASSWORD=IR6X4_ensgm5EclNYQ9kkQ Environment=POSTGRES_DB=appdb Volume=webapp-db:/var/lib/postgresql/data:Z 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/webapp.pod nano ~/.config/containers/systemd/webapp-nginx.container nano ~/.config/containers/systemd/webapp-app.container nano ~/.config/containers/systemd/webapp-postgres.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 webapp-pod.service
Status & Logs
systemctl --user status webapp-pod.service journalctl --user -u webapp-nginx.service -f journalctl --user -u webapp-app.service -f journalctl --user -u webapp-postgres.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 webapp-nginx podman logs -f webapp-app podman logs -f webapp-postgres podman exec -it webapp-nginx /bin/sh
Restart
systemctl --user restart webapp-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 webapp-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 webapp-pod.service rm ~/.config/containers/systemd/webapp.pod rm ~/.config/containers/systemd/webapp-nginx.container rm ~/.config/containers/systemd/webapp-app.container rm ~/.config/containers/systemd/webapp-postgres.container systemctl --user daemon-reload
Delete the data — permanent, only after stop & remove
podman volume rm webapp-nginx podman volume rm webapp-app podman volume rm webapp-db
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 - webapp.
apt install -y podman-compose
Save the compose file
services:
nginx:
image: docker.io/nginx:stable
restart: always
depends_on:
postgres:
condition: service_started
volumes:
- webapp-nginx:/etc/nginx/conf.d:Z
network_mode: service:postgres
app:
image: docker.io/python:3.12-slim
restart: always
environment:
- DATABASE_URL=postgresql://appuser:IR6X4_ensgm5EclNYQ9kkQ@127.0.0.1:5432/appdb
entrypoint:
- python
- -m
- http.server
- '8000'
- --directory
- /app
depends_on:
postgres:
condition: service_started
volumes:
- webapp-app:/app:Z
network_mode: service:postgres
postgres:
image: docker.io/postgres:16
restart: always
environment:
- POSTGRES_USER=appuser
- POSTGRES_PASSWORD=IR6X4_ensgm5EclNYQ9kkQ
- POSTGRES_DB=appdb
user: 999:999
volumes:
- webapp-db:/var/lib/postgresql/data:Z
ports:
- 8080:80
- 8000:8000
volumes:
webapp-nginx: null
webapp-app: null
webapp-db: null
mkdir -p ~/webapp nano ~/webapp/docker-compose.yml
Start, status & logs
cd ~/webapp 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 ~/webapp 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 webapp_nginx_1 podman logs -f webapp_app_1 podman logs -f webapp_postgres_1 podman exec -it webapp_nginx_1 /bin/sh
Restart
cd ~/webapp podman-compose restart
Stop & remove
cd ~/webapp podman-compose down
Delete the data — permanent, only after stop & remove
podman volume rm webapp_webapp-nginx podman volume rm webapp_webapp-app podman volume rm webapp_webapp-db
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 webapp-nginx || podman volume create webapp-nginx podman volume exists webapp-app || podman volume create webapp-app podman volume exists webapp-db || podman volume create webapp-db # ── Create pod ───────────────────────────────────────────────────── podman pod create \ --name webapp \ -p 8080:80 \ -p 8000:8000 # ── Container: webapp-nginx ───────────────────────────────────────────── podman create \ --pod webapp \ --name webapp-nginx \ --restart always \ -v webapp-nginx:/etc/nginx/conf.d:Z \ docker.io/nginx:stable # ── Container: webapp-app ───────────────────────────────────────────── podman create \ --pod webapp \ --name webapp-app \ --restart always \ -e DATABASE_URL='postgresql://appuser:IR6X4_ensgm5EclNYQ9kkQ@127.0.0.1:5432/appdb' \ -v webapp-app:/app:Z \ --entrypoint python \ docker.io/python:3.12-slim \ -m http.server 8000 --directory /app # ── Container: webapp-postgres ───────────────────────────────────────────── podman create \ --pod webapp \ --name webapp-postgres \ --restart always \ -e POSTGRES_USER='appuser' \ -e POSTGRES_PASSWORD='IR6X4_ensgm5EclNYQ9kkQ' \ -e POSTGRES_DB='appdb' \ -v webapp-db:/var/lib/postgresql/data:Z \ --user 999:999 \ docker.io/postgres:16 # ── Start pod ────────────────────────────────────────────────────── podman pod start webapp # ── Stop & clean up ─────────────────────────────────────────────── # podman pod stop webapp # podman pod rm webapp
nano webapp.sh
Run it, status & logs
bash webapp.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 webapp bash webapp.sh
Day-to-day logs, restart, update, remove (click to open)
Logs & shell into a container
podman logs -f webapp-nginx podman logs -f webapp-app podman logs -f webapp-postgres podman exec -it webapp-nginx /bin/sh
Restart
podman pod stop webapp podman pod start webapp
Stop & remove
podman pod rm -f webapp
Delete the data — permanent, only after stop & remove
podman volume rm webapp-nginx podman volume rm webapp-app podman volume rm webapp-db
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