Forgejo on Debian 13 with Rootless Podman
Forgejo as a rootless Podman container under its own user: a Quadlet for systemd, Caddy in front, SSH on port 2222 and the problems I ran into.
Reviewed by adrian
on
Forgejo runs on my VPS as a rootless Podman container under its own user, with Caddy as reverse proxy, a Quadlet for systemd and SSH access on a port of its own. The server had the baseline setup before.
Tested on:
- Debian 13 (Trixie)
- Podman 5.4.2
- VPS: 4 CPU cores, 4 GB RAM (Hetzner)
- Caddy as reverse proxy
1. Install the prerequisites
sudo apt install podman uidmap passt slirp4netns
uidmap: needed for rootless Podman (user namespace mapping).passt: network backend for rootless containers.slirp4netns: alternative network backend.
2. Add the hostname to /etc/hosts
To avoid sudo warnings (unable to resolve host):
sudo nano /etc/hosts
Add the line:
127.0.0.1 <hostname>
3. Create a dedicated user
Forgejo runs rootless under its own git user:
sudo useradd -m -s /bin/bash git
sudo loginctl enable-linger git
enable-linger keeps the systemd user service running without an active login session.
4. Switch to the git user
sudo su - git
5. Create the directories
mkdir -p ~/forgejo-data
mkdir -p ~/.config/containers/systemd
6. Pull the image
podman pull codeberg.org/forgejo/forgejo:10-rootless
The image comes straight from Codeberg, not from Docker Hub.
7. Set the volume permissions
The rootless image runs with a different UID inside the container. Set the permissions with podman unshare:
podman unshare chown -R 1000:1000 ~/forgejo-data
8. Create the Quadlet file
Quadlets are systemd unit files for Podman containers.
cat > ~/.config/containers/systemd/forgejo.container << 'EOF'
[Unit]
Description=Forgejo
After=network-online.target
[Container]
ContainerName=forgejo
Image=codeberg.org/forgejo/forgejo:10-rootless
Network=host
Volume=%h/forgejo-data:/var/lib/gitea
Volume=/etc/timezone:/etc/timezone:ro
Volume=/etc/localtime:/etc/localtime:ro
Label=io.containers.autoupdate=registry
[Service]
Restart=always
[Install]
WantedBy=default.target
EOF
Important: SSH from outside only works with Network=host. With pasta, the default rootless network backend, external SSH connections are not forwarded correctly.
9. Start the container
systemctl --user daemon-reload
systemctl --user start forgejo.service
systemctl --user status forgejo.service
10. Initial setup in the browser
Open http://VPS-IP:3000 and the setup wizard appears. My settings:
- Database type: SQLite (enough for personal use)
- Domain:
git.your-domain.com - Root URL:
https://git.your-domain.com/ - Create an admin account
11. Configure app.ini
After the initial setup, adjust the configuration:
podman unshare nano ~/forgejo-data/custom/conf/app.ini
Add to the [server] block:
[server]
SSH_DOMAIN = git.your-domain.com
SSH_PORT = 2222
SSH_LISTEN_PORT = 2222
START_SSH_SERVER = true
BUILTIN_SSH_SERVER_USER = git
In the [service] block:
[service]
DISABLE_REGISTRATION = true
Restart Forgejo:
systemctl --user restart forgejo.service
12. Set up Caddy as reverse proxy
As a regular user, create a new file:
sudo nano /etc/caddy/sites/forgejo.caddy
Contents:
git.your-domain.com {
reverse_proxy localhost:3000
}
Reload Caddy:
sudo systemctl reload caddy
Caddy gets a TLS certificate from Let's Encrypt on its own.
13. Configure DNS
In Cloudflare (or another DNS provider):
| Type | Name | Content | Proxy |
|---|---|---|---|
| A | * | VPS IP address | DNS only |
| A | @ | VPS IP address | DNS only |
Important: the Cloudflare proxy (orange cloud) must be off, so Caddy can get the TLS certificate itself.
14. Firewall (Hetzner)
In the Hetzner Cloud Console, under Firewall, Inbound Rules:
| Protocol | Port | Source |
|---|---|---|
| TCP | 80 | 0.0.0.0/0, ::/0 |
| TCP | 443 | 0.0.0.0/0, ::/0 |
| TCP | 2222 | 0.0.0.0/0, ::/0 |
| TCP | 22 | 0.0.0.0/0, ::/0 |
15. Set up the SSH key
Show the local SSH key:
cat ~/.ssh/id_ed25519.pub
Add it in Forgejo under Profile → Settings → SSH / GPG Keys → Add Key.
Test SSH:
ssh -p 2222 -T [email protected]
# Hi there, username! You've successfully authenticated...
Local ~/.ssh/config:
Host git.your-domain.com
Port 2222
User git
IdentityFile ~/.ssh/id_ed25519
16. Push the repository
cd /path/to/project
git remote set-url origin ssh://[email protected]:2222/username/repo.git
git push -u origin main
Known problems and fixes
newuidmap: executable file not found
sudo apt install uidmap
pasta: executable file not found
sudo apt install passt
Permission denied on the volume
podman unshare chown -R 1000:1000 ~/forgejo-data
SSH doesn't work from outside
Rootless Podman with pasta doesn't forward external SSH connections. The fix is Network=host in the Quadlet file.
fail2ban blocks SSH connections
After too many failed attempts the IP address gets banned:
sudo fail2ban-client status sshd
sudo fail2ban-client set sshd unbanip YOUR_IP
To keep port 2222 out of fail2ban, create /etc/fail2ban/jail.local:
[sshd]
port = ssh
sudo systemctl restart fail2ban
Two containers running at the same time
After a rename, old containers can keep running and hold the port:
sudo podman ps # show all running containers
sudo podman rm -f <old-container-id>
sudo podman rmi localhost/old-image-name:latest
Podman build uses an old cache
The build service needs --no-cache. In /etc/systemd/system/[email protected]:
ExecStart=/usr/bin/podman-compose up -d --build --no-cache
Useful commands
# Check the status (as the git user)
systemctl --user status forgejo.service
# Follow the logs
journalctl --user -u forgejo.service -f
# Restart the container
systemctl --user restart forgejo.service
# Edit the configuration
podman unshare nano ~/forgejo-data/custom/conf/app.ini
# Automatic updates
podman auto-update
# Show running containers
podman ps
Resource usage
Forgejo needs little: about 130 to 145 MB of RAM in operation, on a machine with 4 GB.
The next step was deploying from Forgejo itself, with a Forgejo Actions runner on the same VPS.
Based on
-
Forgejo on Debian 13 with Rootless Podman
(
raw/2026/2026-04-03/forgejo-on-debian-13-with-rootless-podman.md) [post]
Topic
- Self-Hosting Running services on a server you control instead of using a provider's hosted version, with the upkeep that comes with it.
Basis for
- Setting Up a Forgejo Actions Runner Push-to-deploy with a self-hosted Forgejo Actions runner on the same VPS: own user, no Docker, narrow sudo rights and secrets kept in Forgejo.
Builds on
- Initial VPS Setup on Debian First steps on a fresh Debian VPS: current packages, automatic security updates, a non-root user and SSH with keys only.
Uses
- Caddy Web server and reverse proxy that obtains and renews TLS certificates on its own, configured in a short Caddyfile.
- Forgejo Git forge to host yourself: repositories, users, SSH access and CI/CD with Forgejo Actions and self-hosted runners. Codeberg runs on it.
- Podman Container engine without a background daemon that runs rootless by default on Linux and uses the same commands on macOS and on a server.