How to Self-Host Forgejo & Gitea Lightweight Private Git Server on Ubuntu VPS

Why Self-Host Private Git Repositories with Forgejo / Gitea?

While public GitHub and GitLab cloud platforms provide reliable version control, hosting proprietary commercial codebases, confidential client projects, and internal automation scripts on third-party SaaS platforms exposes organizations to policy changes, code scraping for AI training, and unexpected account suspensions. Additionally, enterprise self-hosted GitLab requires heavy computing resources (minimum 4GB to 8GB RAM).

Forgejo (the community-governed soft-fork of Gitea) is an ultra-lightweight, high-performance private Git server written in Go. Offering full feature parity with GitHub—including pull requests, issue trackers, wiki pages, code reviews, container package registries, and native Actions CI/CD workflows—Forgejo runs smoothly on an affordable 1GB RAM cloud VPS while consuming less than 80MB of memory.

In this technical tutorial, we will configure Forgejo on Ubuntu 24.04/22.04 LTS backed by PostgreSQL with Docker Compose, configure SSH Git operations, and protect the web portal behind an Nginx reverse proxy with SSL encryption.

Step 1: Installing Docker Engine and Project Directory Setup

# Install Docker and prerequisite utilities
sudo apt update && sudo apt install -y curl nginx certbot python3-certbot-nginx
curl -fsSL https://get.docker.com | sudo sh
sudo systemctl enable --now docker

# Create project directory
sudo mkdir -p /var/www/forgejo
sudo chown -R $USER:$USER /var/www/forgejo
cd /var/www/forgejo

Step 2: Writing Production Docker Compose with PostgreSQL

Create /var/www/forgejo/docker-compose.yml:

services:
  db:
    image: postgres:16-alpine
    container_name: forgejo_db
    restart: always
    environment:
      POSTGRES_USER: forgejo_user
      POSTGRES_PASSWORD: UltraStrongGitDbPass2026!
      POSTGRES_DB: forgejo_db
    volumes:
      - postgres_data:/var/lib/postgresql/data

  server:
    image: codeberg.org/forgejo/forgejo:7.0
    container_name: forgejo_server
    restart: always
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=db:5432
      - FORGEJO__database__NAME=forgejo_db
      - FORGEJO__database__USER=forgejo_user
      - FORGEJO__database__PASSWD=UltraStrongGitDbPass2026!
      - FORGEJO__server__ROOT_URL=https://git.example.com
      - FORGEJO__server__SSH_PORT=2222
      - FORGEJO__server__SSH_LISTEN_PORT=22
    ports:
      - "127.0.0.1:3000:3000"
      - "2222:22"
    volumes:
      - forgejo_data:/data
    depends_on:
      - db

volumes:
  postgres_data:
  forgejo_data:

Start the container fleet: docker compose up -d.

Step 3: Nginx Reverse Proxy with SSL Encryption

Create /etc/nginx/sites-available/git.example.com:

server {
    listen 80;
    server_name git.example.com;

    client_max_body_size 200M;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable the site and issue an SSL certificate:

sudo ln -s /etc/nginx/sites-available/git.example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d git.example.com

Setting Up Forgejo Actions CI/CD with Act Runner

Forgejo includes native compatibility with GitHub Actions workflows. Deploy the lightweight act_runner daemon on your VPS to execute automated testing, build, and deployment pipelines:

# Download act_runner binary
curl -L https://code.forgejo.org/forgejo/runner/releases/download/v3.4.0/act_runner-3.4.0-linux-amd64 -o /usr/local/bin/act_runner
chmod +x /usr/local/bin/act_runner

# Register runner with your Forgejo instance
act_runner register --instance https://git.example.com --token <YOUR_RUNNER_REGISTRATION_TOKEN> --no-interactive

# Start runner daemon
act_runner daemon

Automating Daily Git Repository Backups

Create nightly atomic backups using the built-in Forgejo CLI dump command: docker exec -t forgejo_server su - git -c "gitea dump -c /data/gitea/conf/app.ini".

Configuring Built-In Container & Package Registry in Forgejo

Forgejo includes an integrated OCI Docker container registry and language package manager (NPM, PyPI, Maven, Composer) out of the box, allowing developers to publish private Docker images and software packages directly to their self-hosted Git server without paying for Docker Hub Pro:

# Authenticate Docker client with self-hosted Forgejo registry
docker login git.example.com -u your_username -p your_access_token

# Tag and push container image
docker tag my-web-app:latest git.example.com/org/my-web-app:1.0.0
docker push git.example.com/org/my-web-app:1.0.0

Forgejo vs Self-Hosted GitLab Resource Comparison

Configuring SSH Key Authentication & Deploy Keys in Forgejo

Forgejo supports cryptographic Ed25519 and RSA public keys for secure command-line Git operations (push/pull). Developers can configure global user SSH keys or repository-specific read-only Deploy Keys for automated CI/CD deployment pipelines:

# Generate dedicated deploy key for web server
ssh-keygen -t ed25519 -C "[email protected]" -f /var/www/.ssh/forgejo_deploy

# In Forgejo Web UI:
# Navigate to Repository > Settings > Deploy Keys > Add Deploy Key
# Paste /var/www/.ssh/forgejo_deploy.pub

Forgejo Webhook Integration with Slack & Discord

Keep development teams synchronized by configuring native webhooks under Repository > Settings > Webhooks. Select Discord or Slack to receive instant notifications on push commits, opened pull requests, issue mentions, and release tag creation.

Forgejo High-Availability & Disaster Recovery Best Practices

• Automate SQLite/PostgreSQL Dumps: Schedule nightly pg_dump cron jobs to capture all issue trackers, commit metadata, and user accounts.
• Mirror Repositories to GitHub: Use Forgejo’s automated push-mirroring feature to synchronize internal repositories to external GitHub organizations continuously.

# .forgejo/workflows/ci.yaml - Automated Build and Test Pipeline
name: Forgejo Continuous Integration
on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: docker
    container:
      image: node:20-alpine
    steps:
      - name: Check out repository code
        uses: actions/checkout@v4
      - name: Install dependencies and execute test suite
        run: |
          npm ci
          npm run lint
          npm test -- --coverage

# Execute full backup archive containing database, git repositories, and configs
docker exec -u git forgejo-server forgejo dump -c /data/gitea/conf/app.ini --file /data/backup.zip

# Encrypt and synchronize backup archive to off-site secure object storage
gpg --symmetric --batch --passphrase "$BACKUP_SECRET" /data/backup.zip
rclone copy /data/backup.zip.gpg s3:enterprise-git-backups/forgejo/