Self-Host Forgejo on Your VPS: Complete 2025 Guide

Forgejo was born in 2022 as a community fork of Gitea, driven by concerns about the project's governance. Its development is entirely community-led, licensed under GPLv3+ since v9.0 (August 2024; MIT before that), with no dependency on a commercial entity. For teams wanting full control over their source code, CI/CD pipelines, and artifacts without relying on GitHub, GitLab, or Bitbucket, Forgejo is one of the lightest options available. The interface will feel familiar to any GitHub user, migration from Gitea is seamless, and GitHub Actions compatibility lowers the barrier to adoption.

Size your VPS according to your actual team size before deploying Forgejo. For 1–5 developers with a few dozen repositories, 1 vCPU and 1 GB RAM are sufficient. For 5–20 developers with active CI/CD, plan for 2 vCPU and 2 GB RAM. Beyond 20 developers or for large repositories (monorepos, binaries), 4 vCPU and 4 GB RAM ensure a smooth experience. For storage, account for your Git repository volume plus 20% headroom for artifacts and backups.

On the network side, three ports must be open in your firewall: port 80 (HTTP, for Let's Encrypt validation), port 443 (HTTPS, web traffic), and port 2222 (Git SSH, to avoid conflicting with the admin SSH on port 22). On the software side, you need Docker Engine ≥ 24, Docker Compose v2, and a domain name pointing to your VPS.

Compatibility with GitHub Actions syntax is broad. Create .forgejo/workflows/ci.yml at the root of your repository:

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: |
          npm ci
          npm test

The runs-on labels correspond to the labels declared when registering the runner. You can define multiple runners with different labels (e.g., arm64, gpu, high-memory) and target the right environment per job. Artifacts and caching work with the same official actions as on GitHub.

A freshly installed Forgejo is functional but not hardened. Here are the six points to address before opening the forge to your team.

Disable public registration. If you did not do it in the wizard, add FORGEJO__service__DISABLE_REGISTRATION=true to the container's environment variables (or DISABLE_REGISTRATION = true in the [service] section of app.ini): only an administrator can then create accounts. On an internal forge, nobody should be able to create an account without an invitation.

Enable 2FA for administrators. Every admin account must enable two-factor authentication under *Settings → Security*. To enforce it, set GLOBAL_TWO_FACTOR_REQUIREMENT in the [security] section of app.ini (admin for administrators, all for every user). The REQUIRE_SIGNIN_VIEW setting only forces users to sign in to view the forge.

SSH keys only. Disable password authentication in the host server's /etc/ssh/sshd_config (PasswordAuthentication no). For Git SSH (port 2222), Forgejo only accepts public keys registered in user profiles — this is its default behavior.

Webhook secrets. When creating each webhook (to external CI, Slack, etc.), always fill in the *Secret* field. Forgejo signs the payload with HMAC-SHA256; your receiver must verify this signature before processing the event.

Private packages. If you use the built-in package registry, remember that a package inherits its owner's visibility: publish it under a private organization or account to restrict it to members. Access tokens for publishing should have minimal scope (write:package only, never a global admin token).

Firewall. Close all ports except 80, 443, and 2222. Port 3000 (internal Forgejo) must never be exposed directly; it is consumed only by the reverse proxy on loopback, which is why the compose file publishes it on 127.0.0.1:3000. A port published by Docker bypasses ufw rules: only this 127.0.0.1 binding keeps it off the Internet.

The Docker update procedure is straightforward and requires only a few seconds of unavailability.

cd /opt/forgejo
# 1. Pull the new image
docker compose pull forgejo

# 2. Back up the database before any migration
docker compose exec db pg_dump -U forgejo forgejo > backup-$(date +%Y%m%d).sql

# 3. Restart the service
docker compose up -d forgejo

# 4. Verify schema migrations
docker compose logs forgejo | grep -i migrat

Forgejo runs its migrations automatically on startup. Check that the logs report no migration error. In case of a migration error, restore the SQL backup and report the issue on the Forgejo tracker. The 17 tag only follows 17.x releases: to move to the next major version, change the tag in the compose file after a full backup, and always read the release notes before jumping major versions. Forgejo refuses to start on a database newer than itself: rolling back means restoring the backup.

SSH connection refused on port 2222. First verify the port is published by Docker (docker compose ps → Ports column). Then test from the client: ssh -p 2222 [email protected]. If the response is PTY allocation request failed, the connection is working — Forgejo responds Hi <user>! You've successfully authenticated. If you get Connection refused, the firewall is blocking the port: ufw allow 2222/tcp.

Runner showing offline in the interface. The runner contacts Forgejo over outbound HTTPS. Verify the runner container can resolve and reach git.yourdomain.com. A self-signed certificate requires mounting your CA in the container. Restart the runner after fixing connectivity: docker compose restart runner.

Push rejected by a pre-receive hook. Forgejo may reject a push if a branch protection rule is active (code review required, mandatory CI tests) or if a file size rule is exceeded. The git error message contains the details. For large binaries (> 100 MB), use Git LFS: Forgejo supports the LFS protocol natively.

Slow interface after several months. Run the Git garbage collector on active repositories from the admin panel: *Site Administration → Dashboard → Maintenance operations*, repository garbage collection task. To automate this, enable the [cron.git_gc_repos] scheduled task in app.ini (ENABLED = true; it runs every 72 h by default).