Why choose Forgejo for your self-hosted forge
Forgejo was born in 2022 out of a disagreement over the governance of Gitea, which had come under the control of a company. The project is now maintained by a nonprofit association and is progressing toward a decentralized forge capable of federation via ActivityPub — the goal being that a repository on one instance can interact with an issue opened from another instance. For anyone who values the longevity and independence of their tooling, Forgejo offers the same technical qualities as Gitea (lightweight, fast, low consumption) while guaranteeing a fully community-driven license and governance. It is the reference forge of Codeberg, which proves its ability to hold up under production load.
Concrete benefits of a self-hosted Forgejo
- Nonprofit association governance: no risk of a commercial pivot of the project.
- Forgejo Actions, compatible with the syntax of GitHub Actions workflows, with no third-party service.
- Painless migration from Gitea: same database and data volume format.
- ActivityPub federation being rolled out to interconnect instances.
- Lightweight footprint identical to Gitea: ideal on a modest VPS.
- 100% free software, with no paid enterprise edition or restricted feature.
Hardware and software prerequisites
Like Gitea, Forgejo is extremely lean. A VPS with 2 vCPU and 2 GB of RAM handles a team of 10 to 20 developers effortlessly; move up to 4 GB if you run Forgejo Actions with runners that compile locally. Reserve 20 to 40 GB of SSD for repositories and history. You need Docker and Docker Compose, a git.yourdomain.com subdomain with an A record to the VPS IP, and a port distinct from the system port 22 for repository SSH (for example 2222).
Deploy Forgejo with Docker and SSL
Initialize the environment
Over SSH on the VPS, install Docker and the Compose plugin, then create /opt/forgejo. Plan for a data subfolder that will contain repositories, configuration and avatars, mounted as a volume to withstand updates.
Write the docker-compose.yml
Use the official image codeberg.org/forgejo/forgejo:latest. Add a postgres:16 service for the database. Mount ./data:/data, set USER_UID/USER_GID to 1000 and publish Forgejo's SSH on the host with "2222:22", keeping port 3000 internal.
Start the stack
Run docker compose up -d, then watch docker compose logs -f forgejo until you see the HTTP server listening on port 3000 and the database responding.
Set up the reverse proxy and SSL
With Caddy: git.yourdomain.com { reverse_proxy localhost:3000 }, the Let's Encrypt certificate is handled automatically. With Traefik or Nginx, proxy to 127.0.0.1:3000 and enable HTTP/2 as well as HTTP-to-HTTPS redirection.
Configure the instance
Go to https://git.yourdomain.com, fill in the PostgreSQL host (db:5432), the HTTPS base URL and the external SSH port 2222. Create the administrator account and disable self-registration for a private instance.
Connect a Forgejo Actions runner
Retrieve the registration token from the administration, then start a forgejo-runner container pointing to your instance. Validate with a minimal .forgejo/workflows/ci.yml workflow that runs echo ok.
If you are migrating from an existing Gitea instance, Forgejo reads the same data volume and the same database directly: stop Gitea, back up, replace the image with Forgejo's in the docker-compose.yml, then restart. The Forgejo version must be compatible with the Gitea version in use — check the version correspondence table before the switch to avoid a one-way schema migration. Always take a snapshot of the VPS before the operation.
Forgejo versus Gitea
| Criterion | Forgejo | Gitea |
|---|---|---|
| Governance | Nonprofit association (Codeberg e.V.) | Commercial company |
| License / model | 100% free, no enterprise edition | Open source with a commercial Gitea Cloud edition |
| Built-in CI/CD | Forgejo Actions (GitHub Actions compatible) | Gitea Actions (GitHub Actions compatible) |
| Federation | ActivityPub in active development | Not a priority |
| RAM consumption | Very low (~200-300 MB) | Very low (~200-300 MB) |
| Cross migration | Reads the Gitea volume and database | Origin of the fork |
| Docker image | codeberg.org/forgejo/forgejo | gitea/gitea |
| Typical use case | Sovereignty and community longevity | General-purpose forge with possible managed services |
