Gitea Installation Lightweight Git Hosting

Gitea is a lightweight, self-hosted Git service written in Go that provides a simple and fast alternative to GitHub or GitLab. With minimal resource requirements, Gitea can run on small servers while providing features like code repositories, issue tracking, pull requests, and webhooks. This guide covers the complete installation process using binary deployment, database configuration, Nginx setup, SSH support, and webhook configuration.

Table of Contents

Prerequisites

Ensure you have:

  • Ubuntu 20.04 LTS or later
  • Root or sudo access
  • A domain name configured in DNS
  • Minimum 1GB RAM (2GB+ recommended)
  • 10GB available disk space
  • Basic Linux administration skills

Update system packages:

sudo apt update && sudo apt upgrade -y

System Requirements

Verify system specifications:

Check system architecture:

uname -m
cat /etc/os-release

Check available resources:

free -h
df -h

Database Setup

Install SQLite (simplest option) or PostgreSQL for larger deployments:

SQLite Setup

No installation required, Gitea can use SQLite directly. Continue to next section.

PostgreSQL Setup

For production installations with multiple users:

sudo apt install -y postgresql postgresql-contrib

Start and enable PostgreSQL:

sudo systemctl start postgresql
sudo systemctl enable postgresql

Create Gitea database:

sudo -u postgres psql << EOF
CREATE DATABASE gitea;
CREATE USER gitea WITH PASSWORD 'SecurePassword123!';
GRANT ALL PRIVILEGES ON DATABASE gitea TO gitea;
\q
EOF

Test connection:

psql -h localhost -U gitea -d gitea
\q

MySQL/MariaDB Setup

Alternatively use MySQL:

sudo apt install -y mariadb-server

Create database:

sudo mysql -u root -p << EOF
CREATE DATABASE gitea;
CREATE USER 'gitea'@'localhost' IDENTIFIED BY 'SecurePassword123!';
GRANT ALL PRIVILEGES ON gitea.* TO 'gitea'@'localhost';
FLUSH PRIVILEGES;
EXIT;
EOF

Gitea User Creation

Create dedicated system user for Gitea:

sudo useradd -r -s /bin/bash -m -d /var/lib/gitea gitea

Create Gitea installation directory:

sudo mkdir -p /opt/gitea
sudo chown -R gitea:gitea /opt/gitea

Create data directory:

sudo mkdir -p /var/lib/gitea/data
sudo chown -R gitea:gitea /var/lib/gitea
sudo chmod -R 750 /var/lib/gitea

Gitea Installation

Download latest Gitea binary:

cd /tmp
wget https://dl.gitea.io/gitea/1.21.0/gitea-1.21.0-linux-amd64

Install binary:

sudo mv gitea-1.21.0-linux-amd64 /opt/gitea/gitea
sudo chmod +x /opt/gitea/gitea

Verify installation:

/opt/gitea/gitea --version

Create required directories:

sudo mkdir -p /etc/gitea
sudo mkdir -p /var/lib/gitea/repositories
sudo mkdir -p /var/lib/gitea/data
sudo chown -R gitea:gitea /var/lib/gitea
sudo chown -R gitea:gitea /etc/gitea
sudo chmod -R 750 /etc/gitea

Nginx Configuration

Install Nginx:

sudo apt install -y nginx

Create Nginx configuration:

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

Add configuration:

server {
    listen 80;
    listen [::]:80;
    server_name git.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name git.example.com;

    ssl_certificate /etc/letsencrypt/live/git.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/git.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    client_max_body_size 100M;

    location / {
        proxy_pass http://localhost: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;
        proxy_http_version 1.1;
        proxy_request_buffering off;
    }
}

Enable site:

sudo ln -s /etc/nginx/sites-available/gitea /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl start nginx
sudo systemctl enable nginx

SSL Certificate Setup

Install Certbot:

sudo apt install -y certbot python3-certbot-nginx

Obtain SSL certificate:

sudo certbot certonly --nginx -d git.example.com

Verify certificate:

sudo openssl x509 -in /etc/letsencrypt/live/git.example.com/fullchain.pem -noout -dates

Set up auto-renewal:

sudo systemctl enable certbot.timer
sudo systemctl start certbot.timer

SSH Configuration

Configure SSH for Gitea:

Create SSH directory for Gitea user:

sudo -u gitea mkdir -p /var/lib/gitea/.ssh
sudo chmod 700 /var/lib/gitea/.ssh

Generate SSH key pair:

sudo -u gitea ssh-keygen -f /var/lib/gitea/.ssh/id_rsa -N ""

Configure SSH for repository access on a custom port (optional):

sudo nano /etc/ssh/sshd_config

Add Gitea-specific settings:

Port 22
Port 2222

Match User gitea
    X11Forwarding no
    AllowTcpForwarding no
    PermitTTY no
    ForceCommand /opt/gitea/gitea serv

Restart SSH:

sudo systemctl restart ssh

Initial Setup

Create systemd service:

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

Add:

[Unit]
Description=Gitea
After=network.target postgresql.service

[Service]
Type=simple
User=gitea
Group=gitea
WorkingDirectory=/var/lib/gitea
Environment="USER=gitea" "HOME=/var/lib/gitea"
ExecStart=/opt/gitea/gitea web -c /etc/gitea/app.ini
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Start Gitea service:

sudo systemctl daemon-reload
sudo systemctl enable gitea
sudo systemctl start gitea

Verify service:

sudo systemctl status gitea

Check logs:

sudo journalctl -u gitea -f

Access Gitea web interface:

Navigate to https://git.example.com and complete the setup:

  1. Database type: PostgreSQL/MySQL/SQLite
  2. Database connection details
  3. Gitea HTTP port: 3000
  4. SSH port: 2222 (or 22)
  5. Base URL: https://git.example.com/
  6. Create admin account

Repository Management

Initialize repository:

  1. Login with admin account
  2. Click "+" icon → New Repository
  3. Set repository name, description, and privacy
  4. Initialize with README

Clone repository:

git clone https://git.example.com/username/repository.git
cd repository

Configure Gitea for your organization:

  1. Admin Panel → System Settings
  2. Configure email notifications
  3. Set repository defaults
  4. Configure authentication methods

Webhooks Configuration

Enable webhooks for automation:

  1. Go to repository settings → Webhooks
  2. Add webhook with:

Create webhook handler:

sudo nano /usr/local/bin/gitea-webhook.sh

Example webhook processor:

#!/bin/bash

WEBHOOK_SECRET="your-secret-key"
WEBHOOK_PAYLOAD="$1"

# Verify webhook signature if configured
# Extract event type and perform action

echo "Webhook received: $WEBHOOK_PAYLOAD" >> /var/log/gitea-webhooks.log

Backup Strategy

Create backup script:

sudo nano /usr/local/bin/gitea-backup.sh

Add:

#!/bin/bash

BACKUP_DIR="/backups/gitea"
GITEA_HOME="/var/lib/gitea"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# Stop Gitea service
sudo systemctl stop gitea

# Create backup
/opt/gitea/gitea dump -c /etc/gitea/app.ini -o "$BACKUP_DIR/gitea-backup-$DATE.zip"

# Start Gitea service
sudo systemctl start gitea

# Keep only 30 days of backups
find $BACKUP_DIR -type f -name "gitea-backup-*.zip" -mtime +30 -delete

echo "Backup completed: $DATE"

Make executable:

sudo chmod +x /usr/local/bin/gitea-backup.sh

Schedule daily backups:

sudo crontab -e

Add:

0 2 * * * /usr/local/bin/gitea-backup.sh >> /var/log/gitea-backup.log 2>&1

Restore from backup:

sudo systemctl stop gitea
cd /opt/gitea
unzip /backups/gitea/gitea-backup-*.zip
sudo systemctl start gitea

Update Gitea:

sudo systemctl stop gitea
cd /tmp
wget https://dl.gitea.io/gitea/latest/gitea-latest-linux-amd64
sudo mv gitea-latest-linux-amd64 /opt/gitea/gitea
sudo chmod +x /opt/gitea/gitea
sudo systemctl start gitea

Conclusion

Gitea is now fully installed as a lightweight, self-hosted Git service. With proper Nginx configuration, SSL encryption, SSH support, and webhook capabilities, you have a complete version control solution. Regular backups and updates maintain system reliability. The minimal resource requirements make Gitea ideal for small teams and organizations seeking self-hosted Git hosting.