Forgejo Docker: Self-Hosted GitHub and Gitea Alternative

If GitHub going down takes your entire workflow with it, you already know the problem. Your code, your issues, your CI pipelines — all renting space on someone else’s servers. Forgejo flips that equation: it is a fully self-hosted software forge that you own and run yourself, and it is lightweight enough to live on hardware you already have.

If you have tried Gitea, Gogs, or GitLab CE, Forgejo sits in the practical middle: more community-governed than Gitea, much lighter than GitLab, and more complete than Gogs.

What is Forgejo?

Forgejo (/for’d͡ʒe.jo/ — from the Esperanto word forĝejo, meaning “forge”) is a community-driven, free/libre Git forge. It was created in December 2022 when concerns about corporate ownership of Gitea prompted the community to establish an independently governed project. The promise has never changed: Free/Libre Software forever, community-owned.

“Forgejo was created because we think that the project should be owned by an independent community.”

Forgejo Source Code on Codeberg Forgejo Official Website

Why self-hosters care

• 🪶 Lightweight — runs on a Raspberry Pi or a $5/month VPS without breaking a sweat
• 🔒 Privacy-first — no telemetry, no tracking, minimal defaults
• 🌐 Federation — ActivityPub support (WIP) connects your forge to the Fediverse
• 📦 All-in-one — Git hosting, issues, PRs, wikis, kanban, CI, and a package registry in a single binary
• ⚖️ GPL v3 licensed — copyleft ensures it stays free ❤️
• 🔄 Gitea-compatible — import from GitHub, GitLab, Gitea with zero friction

Forgejo Tech Overview

Forgejo’s backend is written in Go, which is why it compiles to a single binary and consumes very little RAM at idle. The frontend is TypeScript + Vue.js, compiled and embedded into that binary at build time — no separate Node.js process needed at runtime.

Key components

Backend (Go 1.26+)

• HTTP routing via chi v5
• Database abstraction via xorm ORM — supports SQLite (default), MySQL, and PostgreSQL
• SSH server (go-based, no system sshd required) for Git-over-SSH
• Full-text search via Bleve (built-in), Elasticsearch, or Meilisearch
• Queue and cache via LevelDB (built-in) or Redis
• Automatic TLS via CertMagic (Let’s Encrypt)
• Object storage: local filesystem or MinIO (S3-compatible)

Authentication

• Local accounts with TOTP 2FA
• WebAuthn / Passkeys
• LDAP / Active Directory
• OAuth2 via 30+ providers (GitHub, GitLab, Google, Keycloak, Authentik, and more)
• PAM, SMTP, OpenID

CI/CD Forgejo includes Forgejo Actions — a built-in CI runner compatible with GitHub Actions YAML syntax. Your existing .github/workflows/ files work without modification.

Federation ActivityPub support is under active development. The goal: issues and pull requests that cross forge boundaries, turning independent instances into a collaborative network.

Self-Hosting Forgejo with Docker

Forgejo does not ship an official docker-compose.yml in its repository, but the community-standard setup is straightforward. The image is published at codeberg.org/forgejo/forgejo.

Basic setup (SQLite)

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:latest
    container_name: forgejo
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: unless-stopped
    volumes:
      - forgejo_data:/data
    ports:
      - "3000:3000"   # Web UI
      - "222:22"      # SSH — host port 222 → container port 22

volumes:
  forgejo_data:

Save this as docker-compose.yml, then:

docker compose up -d

Open http://localhost:3000 — the first-run wizard walks you through:

1. Database selection (SQLite is fine for personal/small-team use)
2. Admin account creation
3. Site title, base URL

services:
  db:
    image: postgres:16-alpine
    container_name: forgejo_db
    environment:
      POSTGRES_USER: forgejo
      POSTGRES_PASSWORD: changeme
      POSTGRES_DB: forgejo
    volumes:
      - forgejo_db:/var/lib/postgresql/data
    restart: unless-stopped

  forgejo:
    image: codeberg.org/forgejo/forgejo:latest
    container_name: forgejo
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=db:5432
      - FORGEJO__database__NAME=forgejo
      - FORGEJO__database__USER=forgejo
      - FORGEJO__database__PASSWD=changeme
    restart: unless-stopped
    volumes:
      - forgejo_data:/data
    ports:
      - "3000:3000"
      - "222:22"
    depends_on:
      - db

volumes:
  forgejo_data:
  forgejo_db:

Services explained

Volume /data holds everything: Git repositories, config (app.ini), uploads, and the SQLite database (if used). Back this up.

Port 3000 is the web UI and REST API. Port 22 (mapped to 222 on the host) handles Git-over-SSH. If you want users to clone with git@yourdomain:user/repo.git on the standard port, map "22:22" instead and ensure your host SSH doesn’t conflict.

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:latest-rootless
    container_name: forgejo
    user: "1000:1000"
    volumes:
      - forgejo_data:/var/lib/gitea
      - forgejo_config:/etc/gitea
    ports:
      - "3000:3000"
      - "222:2222"
    restart: unless-stopped

volumes:
  forgejo_data:
  forgejo_config:

Reverse Proxy and HTTPS

For a public Forgejo instance, put it behind HTTPS before inviting users. The common pattern is:

1. Run Forgejo on Docker port 3000.
2. Put Traefik, Caddy, or Nginx Proxy Manager in front.
3. Set the public root URL in app.ini, for example ROOT_URL = https://git.example.com/.
4. Expose SSH on a predictable port such as 222 unless the host’s own SSH can move away from port 22.

If your Forgejo instance is only for a private homelab, a VPN such as Tailscale/Headscale is often simpler than exposing it publicly.

Forgejo vs Gitea vs GitLab

The short version: use Forgejo when you want a lightweight Git forge with community governance. Use Gitea when you prefer the upstream ecosystem. Use GitLab only when you actually need the larger integrated DevOps platform and can afford the RAM.

Conclusion

Forgejo delivers everything you would expect from a modern Git forge — repository hosting, issue tracking, pull requests, wikis, kanban, a package registry, and built-in CI — wrapped in a single Go binary that respects your hardware constraints and your privacy.

The community-first governance model means there are no surprise license changes, no VC roadmap overrides, and no telemetry. If self-sovereignty over your source code matters, Forgejo is the straightforward answer.

Alternatives to consider:

• Gitea — Forgejo’s upstream; similar feature set, commercial backing
• GitLab CE — far more features, far heavier resource requirements
• Gogs — even lighter, fewer features, older codebase

For most self-hosters, Forgejo hits the sweet spot: complete enough for a team, light enough for a Raspberry Pi.