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.

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.

More on this

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.

Show in the graph view →