Forgejo Deployment Guide

Prerequisites

Forgejo is a fork of Gitea, prioritizing privacy, federation, and open governance under the Codeberg e.V. nonprofit organization.

Server Requirements

• RamNode VPS with 1GB+ RAM (2GB recommended)
• Ubuntu 24.04 LTS
• Root or sudo access
• Domain name (recommended for SSL)

→ View Recommended VPS Plans

Key Features

• Repository management
• Issues & pull requests
• CI/CD with Forgejo Actions
• Git LFS support
• OAuth & SSO integration
• Federation capabilities

Server Preparation

Connect to your VPS via SSH and prepare the system:

Update System & Install Dependencies

sudo apt update && sudo apt upgrade -y
sudo apt install -y git git-lfs curl wget gnupg2 ca-certificates

Configure Firewall

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 3000/tcp
sudo ufw enable

Method 1: Binary Installation

Maximum control, ideal for production environments with fine-grained configuration.

Create Forgejo User & Directories

Create Dedicated User

sudo adduser --system --shell /bin/bash --gecos 'Git Version Control' \
  --group --disabled-password --home /home/git git

Create Directory Structure

sudo mkdir -p /var/lib/forgejo
sudo chown git:git /var/lib/forgejo
sudo chmod 750 /var/lib/forgejo

sudo mkdir -p /etc/forgejo
sudo chown root:git /etc/forgejo
sudo chmod 770 /etc/forgejo

Download & Install Forgejo Binary

Download Forgejo

cd /tmp
wget https://codeberg.org/forgejo/forgejo/releases/download/v13.0.4/forgejo-13.0.4-linux-amd64
wget https://codeberg.org/forgejo/forgejo/releases/download/v13.0.4/forgejo-13.0.4-linux-amd64.asc

Verify GPG Signature (Optional)

gpg --keyserver keys.openpgp.org --recv EB114F5E6C0DC2BCDD183550A4B61A2DC5923710
gpg --verify forgejo-13.0.4-linux-amd64.asc forgejo-13.0.4-linux-amd64

Install Binary

sudo cp forgejo-13.0.4-linux-amd64 /usr/local/bin/forgejo
sudo chmod 755 /usr/local/bin/forgejo
forgejo --version

Configure Database

Forgejo supports SQLite, PostgreSQL, and MySQL/MariaDB. Choose one:

Option A: SQLite (Simplest)

No additional setup required. Works well for fewer than 100 users. The database file is created automatically during initial configuration.

Option B: PostgreSQL (Recommended for Production)

Install PostgreSQL

sudo apt install -y postgresql postgresql-contrib

Create Database & User

sudo -u postgres psql

CREATE USER forgejo WITH PASSWORD 'your_secure_password_here';
CREATE DATABASE forgejodb OWNER forgejo;
\q

Option C: MySQL/MariaDB

Install MariaDB

sudo apt install -y mariadb-server
sudo mysql_secure_installation

Create Database & User

sudo mysql

CREATE DATABASE forgejodb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'forgejo'@'localhost' IDENTIFIED BY 'your_secure_password_here';
GRANT ALL PRIVILEGES ON forgejodb.* TO 'forgejo'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Create Systemd Service

Download Service File

sudo wget -O /etc/systemd/system/forgejo.service \
  https://codeberg.org/forgejo/forgejo/raw/branch/forgejo/contrib/systemd/forgejo.service

If using PostgreSQL, edit the service file to uncomment dependencies:

Edit Service File

sudo nano /etc/systemd/system/forgejo.service

Uncomment for PostgreSQL

Wants=postgresql.service
After=postgresql.service

Or for MariaDB

Wants=mariadb.service
After=mariadb.service

Start Forgejo

sudo systemctl daemon-reload
sudo systemctl enable forgejo
sudo systemctl start forgejo

✅ Success! Access the web setup at http://YOUR_VPS_IP:3000

Complete Web-Based Setup

Configure the following in the web installer:

Database Settings

Select your database type and enter credentials

General Settings

Site title, domain, SSH domain, base URL

Administrator Account

Create admin username, email, and password

Install

Click "Install Forgejo" to complete

Lock Down Configuration After Install

sudo chmod 750 /etc/forgejo
sudo chmod 640 /etc/forgejo/app.ini

Method 2: Docker Installation

Easier updates and isolation. Ideal for quick deployments.

Install Docker

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
sudo apt install -y docker-compose-plugin

Log out and back in for group changes to take effect.

Create Docker Compose Configuration

Create Directory Structure

mkdir -p ~/forgejo/{data,config}
cd ~/forgejo
nano docker-compose.yml

With SQLite (Simple Setup):

docker-compose.yml (SQLite)

networks:
  forgejo:
    external: false

services:
  server:
    image: codeberg.org/forgejo/forgejo:13
    container_name: forgejo
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: always
    networks:
      - forgejo
    volumes:
      - ./data:/data
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "22:22"

With PostgreSQL (Production Setup):

docker-compose.yml (PostgreSQL)

networks:
  forgejo:
    external: false

services:
  server:
    image: codeberg.org/forgejo/forgejo:13
    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=your_secure_password_here
    restart: always
    networks:
      - forgejo
    volumes:
      - ./data:/data
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
    depends_on:
      - db

  db:
    image: postgres:16
    container_name: forgejo-db
    restart: always
    environment:
      - POSTGRES_USER=forgejo
      - POSTGRES_PASSWORD=your_secure_password_here
      - POSTGRES_DB=forgejo
    networks:
      - forgejo
    volumes:
      - ./postgres:/var/lib/postgresql/data

Start Forgejo

docker compose up -d
docker compose ps

Set Up Reverse Proxy with SSL

Install Nginx

sudo apt install -y nginx

Create Nginx Configuration

sudo nano /etc/nginx/sites-available/forgejo

/etc/nginx/sites-available/forgejo

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

    location / {
        proxy_pass http://127.0.0.1:3000;
        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;

        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Large repositories
        client_max_body_size 512M;
        proxy_buffering off;
    }
}

Enable Site & Get SSL

sudo ln -s /etc/nginx/sites-available/forgejo /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# Install Certbot and get SSL certificate
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d git.yourdomain.com

Update Forgejo's ROOT_URL in app.ini or Docker environment:

Update Configuration

[server]
ROOT_URL = https://git.yourdomain.com/

SSH Configuration

By default, Forgejo uses port 22 for SSH, which may conflict with your system's SSH server.

Option 1: Use Different Port for Forgejo SSH

For binary installation, edit /etc/forgejo/app.ini:

app.ini

[server]
SSH_PORT = 2222
SSH_LISTEN_PORT = 2222

For Docker, modify port mapping:

docker-compose.yml ports

ports:
  - "3000:3000"
  - "2222:22"

Update Firewall

sudo ufw allow 2222/tcp

Option 2: SSH Passthrough (Advanced)

Configure system SSH to pass Git commands to Forgejo. Edit /etc/ssh/sshd_config:

sshd_config

AcceptEnv GIT_PROTOCOL

Restart SSH

sudo systemctl restart sshd

Post-Installation Configuration

Edit your configuration file with production-ready settings:

Recommended app.ini Settings

[server]
DOMAIN = git.yourdomain.com
ROOT_URL = https://git.yourdomain.com/
HTTP_PORT = 3000
SSH_PORT = 22
DISABLE_SSH = false
OFFLINE_MODE = false
LFS_START_SERVER = true

[database]
SQLITE_JOURNAL_MODE = WAL

[service]
DISABLE_REGISTRATION = false
REQUIRE_SIGNIN_VIEW = false
REGISTER_EMAIL_CONFIRM = false
ENABLE_CAPTCHA = true

[session]
PROVIDER = file

[log]
MODE = console, file
LEVEL = info
ROOT_PATH = /var/lib/forgejo/log

[security]
INSTALL_LOCK = true
SECRET_KEY = your_generated_secret_key
INTERNAL_TOKEN = your_generated_internal_token

[mailer]
ENABLED = true
PROTOCOL = smtps
SMTP_ADDR = smtp.youremailprovider.com
SMTP_PORT = 465
USER = your_email@yourdomain.com
PASSWD = your_email_password
FROM = "Forgejo" <noreply@yourdomain.com>

Enable Forgejo Actions (CI/CD)

Enable the built-in CI/CD feature:

Add to app.ini

[actions]
ENABLED = true

💡 Tip: You'll need to install a runner to execute workflows. See the Forgejo Actions documentation for detailed runner setup instructions.

Maintenance & Upgrades

Backup Strategy

Create Backup

# Binary installation
sudo -u git forgejo dump -c /etc/forgejo/app.ini

# Docker installation
docker exec -u git forgejo forgejo dump -c /data/gitea/conf/app.ini

This creates a ZIP archive containing repositories, database, and configuration.

Upgrading Forgejo

Binary Upgrade

sudo systemctl stop forgejo
cd /tmp
wget https://codeberg.org/forgejo/forgejo/releases/download/vX.Y.Z/forgejo-X.Y.Z-linux-amd64
sudo cp forgejo-X.Y.Z-linux-amd64 /usr/local/bin/forgejo
sudo chmod 755 /usr/local/bin/forgejo
sudo systemctl start forgejo

Docker Upgrade

cd ~/forgejo
docker compose pull
docker compose up -d

View Logs

Check Logs

# Binary installation
sudo journalctl -u forgejo.service -f

# Docker installation
docker logs -f forgejo

Troubleshooting

Port 3000 Already in Use

Find Conflicting Process

sudo lsof -i :3000
# Kill the conflicting process or change Forgejo's HTTP_PORT

Permission Denied Errors

Fix Permissions

sudo chown -R git:git /var/lib/forgejo
sudo chown -R git:git /etc/forgejo

Database Connection Failed

• Verify database credentials in app.ini
• Check that the database service is running
• Ensure the database user has proper permissions

SSH Cloning Not Working

• Verify SSH port matches firewall rules
• Check git user's .ssh/authorized_keys file
• Test connectivity: ssh -T git@yourdomain.com -p 22

Large File Upload Failures

• Increase client_max_body_size in Nginx
• Enable and configure Git LFS for large files

🎉 Congratulations!

Forgejo is now running on your RamNode VPS! You have a fully-featured, privacy-focused Git forge for your personal projects, team, or organization.