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