Forgejo: Your Own GitHub

What You'll Build

Forgejo is a lightweight Git server with a GitHub-style web interface: repositories, issues, pull requests, wikis, and more. Perfect for private projects and for keeping every compose.yaml from this site under version control — so you can see exactly what you changed and roll back.

Ports: 3002 (web), 2222 (Git over SSH) · RAM: ~200 MB · Time: 30 minutes · Difficulty: Easy

What You Need

• Your home server from Foundations 1 (Docker installed, ~/stacks folder).
• Nginx Proxy Manager with your *.home.example.com certificate (recommended).
• Git installed on your own computer (sudo apt install git) and an SSH key (ssh-keygen -t ed25519).

Step 1: Start Forgejo

mkdir -p ~/stacks/forgejo/data && cd ~/stacks/forgejo
nano compose.yaml

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:16     # use the current major version from forgejo.org
    container_name: forgejo
    restart: unless-stopped
    environment:
      USER_UID: 1000            # must own ./data
      USER_GID: 1000
    ports:
      - "3002:3000"             # web interface (3000 is taken by Homepage)
      - "2222:22"               # Git over SSH (22 is the server's own SSH)
    volumes:
      - ./data:/data
      - /etc/localtime:/etc/localtime:ro

docker compose up -d

Step 2: The First-Run Install Page

1. Open http://192.168.1.50:3002. The initial configuration page appears.
2. Database: SQLite3 (fine for personal use).
3. Server domain: git.home.example.com · SSH server port: 2222 · Base URL: https://git.home.example.com/
4. Under Server and third-party service settings, tick Disable self-registration.
5. Under Administrator account settings, create your admin user → Install Forgejo.

Step 3: Add Your SSH Key and Push a Repository

1. On your computer: cat ~/.ssh/id_ed25519.pub and copy it.
2. Forgejo → avatar → Settings → SSH / GPG keys → Add key → paste.
3. + → New repository → name it homelab, Private → Create.

# Put your server's stacks folder under version control (run on the server)
cd ~/stacks
git init
printf '*/data/\n*/postgres/\n*/.env\n' > .gitignore   # never commit data or secrets!
git add . && git commit -m "All my compose files"

git remote add origin ssh://git@git.home.example.com:2222/yourname/homelab.git
git push -u origin main

Step 4: Mirror Your GitHub Repos (Optional)

+ → New Migration → GitHub, paste a repository URL, and tick This repository will be a mirror. Forgejo keeps a copy synced on a schedule — a backup of your code in case a GitHub account is ever lost.

Add It to Your Proxy, Dashboard, and Backups

• Nginx Proxy Manager: new proxy host git.home.example.com → scheme http, 192.168.1.50, port 3002, Websockets on, your wildcard certificate, Force SSL.
• Homepage: add a tile in services.yaml (how).
• Uptime Kuma: add an HTTP monitor for the new address (how).
• Backups: ~/stacks/forgejo is already covered by the restic script.

Troubleshooting

• Container won't start: permission denied — ./data must be owned by UID 1000: sudo chown -R 1000:1000 ~/stacks/forgejo/data.
• SSH push asks for a password — you're using port 22. Use the ssh://…:2222/ URL shown on the repository page, and check the key was added.
• Clone URLs show localhost — fix the domain and ROOT_URL in data/gitea/conf/app.ini, then restart.

What's Next?