Self-Hosting Gitea on Linux VPS in Pakistan: Lightweight Private Git Server & CI/CD Guide

The software export industry in Pakistan has expanded into an international engineering powerhouse. Software houses in Lahore, enterprise development firms in Karachi, and emerging artificial intelligence and SaaS collectives in Islamabad routinely deliver mission-critical digital products for clients across North America, the United Kingdom, and the Middle East.

Yet, despite this technological maturity, an overwhelming number of Pakistani technology companies remain tethered to centralized, US-denominated Software-as-a-Service (SaaS) platforms for their primary source code repositories. Platforms such as GitHub Enterprise and GitLab Cloud charge aggressive, per-seat recurring subscription models in US Dollars.

For local engineering leaders, this model presents continuous operational friction: volatile foreign exchange spreads, stringent corporate credit card transaction caps imposed by the State Bank of Pakistan (SBP), heavy advance withholding taxes, and legal compliance risks surrounding client Non-Disclosure Agreements (NDAs) and intellectual property sovereignty.

Deploying a self-hosted instance of Gitea on a high-performance Linux Virtual Private Server (VPS) provides Pakistani software houses with an ultra-lightweight, resilient, and sovereign Git infrastructure. Gitea delivers a complete GitHub-equivalent workflow—including pull requests, code reviews, issue tracking, Git Large File Storage (LFS), built-in package registries, and fully compatible CI/CD Actions—while running comfortably on a fraction of the hardware resources required by GitLab.

This technical guide delivers an end-to-end production deployment blueprint for systems administrators, DevOps leads, and agency CTOs migrating to a self-hosted Gitea architecture on Ubuntu Linux.

---

The Economic and Regulatory Friction of Cloud Git in Pakistan

For a software development agency or IT export house employing between 25 and 100 engineers, licensing commercial SaaS code hosting platforms introduces substantial administrative and financial overhead.

The Per-Seat USD Currency Drain

Commercial cloud Git platforms structure their monetization around strict per-user monthly tiers:

• GitHub Team / Enterprise: Ranges from $4 to $21 per user per month.
• GitLab Premium / Ultimate: Ranges from $29 to $99 per user per month.

For an agency with 50 developers on GitHub Enterprise, the baseline license cost totals $1,050 USD per month ($12,600 USD annually). Under prevailing Pakistani Rupee exchange rates (PKR 280–300 per USD), that single recurring expense drains between PKR 3,500,000 and PKR 3,780,000 annually directly from operational margins.

Furthermore, these tiers force agencies into difficult trade-offs: either paying for occasional contributors, quality assurance testers, and project managers, or practicing insecure shared credential patterns that violate organizational security policies.

Banking FX Restrictions and SBP Advance Withholding Taxes

Operating software subscriptions from Pakistan involves significant institutional friction:

1. Statutory Card Caps: Corporate credit and debit cards face monthly foreign exchange quota limits established under SBP prudential regulations. Agencies frequently find automated subscription billing blocked unexpectedly due to monthly transaction ceilings.
2. Advance Withholding Tax (WHT): Under Section 236Y of the Income Tax Ordinance, outward international digital card remittances carry a 5% Advance Withholding Tax for active taxpayers (and 10% for non-filers).
3. Foreign Exchange Markups: Commercial banks levy an additional 3% to 5% foreign currency conversion spread over interbank rates.

A nominal $1,050 USD invoice routinely translates into an actual local expenditure equivalent to $1,150+ USD once local taxes and currency conversion fees are settled.

Source Code Sovereignty and Client NDAs

Pakistani IT export firms build proprietary systems for global healthcare providers, fintech institutions, defense vendors, and enterprise SaaS companies. Many international master service agreements (MSAs) strictly prohibit hosting proprietary codebase assets on shared public cloud infrastructure where multi-tenant telemetry, terms-of-service changes, or foreign jurisdiction data subpoenas could compromise confidentiality.

Self-hosting Gitea on private Linux infrastructure guarantees that:

• Proprietary source code never leaves private, controlled storage volumes.
• Access logs, developer activity, and intellectual property remain 100% sovereign.
• Storage capacity can scale without triggering arbitrary per-gigabyte SaaS pricing penalties.

---

Architectural Comparison: Gitea vs. GitLab vs. Cloud SaaS

When software teams consider leaving commercial SaaS, the discussion often turns to GitLab Community Edition (CE). However, for small-to-mid agencies, GitLab introduces massive infrastructural overhead.

Architectural Dimension	Gitea (Docker / Linux VPS)	GitLab CE (Self-Hosted)	GitHub Enterprise Cloud
Primary Language / Runtime	Go (Single Compiled Binary)	Ruby on Rails, Go, Java, Vue	Proprietary Cloud Stack
Idle Memory Footprint	80 MB – 150 MB RAM	4 GB – 8 GB RAM	Managed (0 MB local)
Recommended Minimum Server	2 vCPU / 2 GB RAM / NVMe	4–8 vCPU / 8–16 GB RAM / NVMe	None (SaaS)
Startup / Boot Time	< 2 seconds	2 – 5 minutes	Immediate
Built-in CI/CD Engine	Gitea Actions (Act Runner)	GitLab CI (GitLab Runner)	GitHub Actions
Workflow Syntax Compatibility	100% GitHub Actions YAML	GitLab CI YAML	GitHub Actions YAML
Package Registries	Built-in (Docker, npm, PyPI, etc.)	Built-in (Requires Object Storage)	Built-in (Usage Billed)
Per-Seat Licensing Cost	$0 / Unlimited Users	$0 (CE) / High RAM Cost	$4 – $21 / user / month
Underlying Database	PostgreSQL, MariaDB, or SQLite	PostgreSQL	Proprietary Spanner / MySQL

Why Gitea Outclasses GitLab for Resource-Efficient Teams

GitLab Omnibus is a sprawling constellation of microservices: Puma application server, Sidekiq background workers, Gitaly Git RPC daemon, Redis cache, PostgreSQL, Prometheus, and Grafana. Even with zero active developer traffic, a baseline GitLab installation consumes 6 GB to 8 GB of RAM.

In contrast, Gitea is compiled into a single static Go binary. Its memory footprint when idle hovers below 100 MB. It communicates with a lean PostgreSQL database, uses native filesystem I/O for repository objects, and routes background jobs through internal Go routines.

A high-performance Linux VPS with 4 vCPUs and 8 GB RAM can comfortably host a Gitea instance supporting 100+ concurrent developers, parallel CI/CD runners, and multiple Git LFS transfer streams without breaking a sweat.

---

Recommended Hardware & VPS Sizing Matrix

To achieve sub-second Git push/pull response times and seamless web interface navigation, allocate server resources according to team size and build intensity:

Engineering Team Size	Concurrent Developers	Recommended VPS Specification	Storage Tier	Target Workloads
Starter (1–15 Devs)	Up to 10	2 vCPU / 4 GB RAM	60 GB Pure NVMe	Code hosting, PR reviews, Webhooks
Growth (15–50 Devs)	Up to 35	4 vCPU / 8 GB RAM	150 GB Pure NVMe	Code hosting, Git LFS, 2x CI/CD Runners
Enterprise (50–120 Devs)	Up to 90	8 vCPU / 16 GB RAM	350 GB Pure NVMe	Multi-project CI/CD, Docker Registries
High-Concurrency (120+ Devs)	100+	Bare-Metal Dedicated Server	1 TB – 2 TB NVMe RAID	Heavy Docker builds, parallel microservices

The Critical Role of Pure NVMe Storage

Git operations are notoriously random-I/O intensive. A routine git fetch or git checkout on a repository containing tens of thousands of files triggers thousands of small read operations across loose objects and packfile indices (.idx).

Standard SATA SSDs or virtualized spindle disks choke under concurrent developer traffic, creating sluggish command-line response times. Deploying on pure NVMe storage ensures 50,000+ random 4K IOPS, ensuring that repository indexing, blame lookups, and packfile generation remain instantaneous.

---

Production Deployment on Ubuntu 24.04/22.04 LTS

We will deploy Gitea using Docker Compose alongside an isolated PostgreSQL 16 container, automated persistent volume mappings, and a hardened system user.

Step 1: System Preparation and Docker Installation

Update system packages and install Docker Engine with the Compose plugin:

# Update base repositories
sudo apt update && sudo apt upgrade -y

# Install prerequisite utilities
sudo apt install -y curl git ufw fail2ban jq htop

# Install Docker via official repository
curl -fsSL https://get.docker.com | sudo sh

# Ensure Docker starts on boot
sudo systemctl enable --now docker

Step 2: Establish Directory Hierarchy

Create a dedicated application directory under /opt/gitea:

sudo mkdir -p /opt/gitea/{data,config,postgres_data,backups}
cd /opt/gitea

Create a dedicated system user git with UID/GID 1000 so file permissions map identically inside and outside the container:

# Create git group and user if not already present
sudo groupadd -g 1000 git || true
sudo useradd -u 1000 -g git -m -s /bin/bash git || true

# Set directory ownership
sudo chown -R 1000:1000 /opt/gitea/data
sudo chown -R 1000:1000 /opt/gitea/config

Step 3: Production Docker Compose Configuration

Create /opt/gitea/docker-compose.yml:

services:
  server:
    image: gitea/gitea:1.22-rootless
    container_name: gitea_server
    restart: always
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=A_Very_Secure_Gitea_Postgres_Password_2026
      - GITEA__server__ROOT_URL=https://git.agency.pk/
      - GITEA__server__SSH_PORT=2222
      - GITEA__server__SSH_LISTEN_PORT=2222
      - GITEA__server__LFS_START_SERVER=true
      - GITEA__packages__ENABLED=true
      - GITEA__actions__ENABLED=true
      - GITEA__security__INSTALL_LOCK=true
    volumes:
      - ./data:/var/lib/gitea
      - ./config:/etc/gitea
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "127.0.0.1:3000:3000"
      - "127.0.0.1:2222:2222"
    depends_on:
      db:
        condition: service_healthy
    networks:
      - gitea_network

  db:
    image: postgres:16-alpine
    container_name: gitea_postgres
    restart: always
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=A_Very_Secure_Gitea_Postgres_Password_2026
      - POSTGRES_DB=gitea
    volumes:
      - ./postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U gitea -d gitea"]
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - gitea_network

networks:
  gitea_network:
    driver: bridge

Start the containers in detached mode:

docker compose up -d

Verify that both containers are running and healthy:

docker compose ps

---

Production Nginx Reverse Proxy with Let’s Encrypt TLS

Gitea should never be exposed directly to the public internet on unencrypted ports. We configure Nginx as a reverse proxy terminating TLS with HTTP/2 and tuned upload buffers.

Step 1: Install Nginx and Certbot

sudo apt install -y nginx certbot python3-certbot-nginx

Step 2: Configure Nginx Virtual Host

Create /etc/nginx/sites-available/gitea.conf:

server {
    listen 80;
    server_name git.agency.pk;

    # Allow Let's Encrypt ACME challenges
    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl http2;
    server_name git.agency.pk;

    # SSL Certificate directives (managed by Certbot)
    ssl_certificate /etc/letsencrypt/live/git.agency.pk/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/git.agency.pk/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    # Security Headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Critical for Git LFS and Container Registry Image Pushes
    client_max_body_size 2048M;
    client_body_buffer_size 128k;

    # Extended timeouts for large repository clones and initial pushes
    proxy_connect_timeout 600s;
    proxy_send_timeout 600s;
    proxy_read_timeout 600s;

    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 for real-time notifications
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Enable the configuration and obtain the SSL certificate:

# Link virtual host
sudo ln -s /etc/nginx/sites-available/gitea.conf /etc/nginx/sites-enabled/

# Test syntax
sudo nginx -t

# Obtain Let's Encrypt certificate
sudo certbot --nginx -d git.agency.pk

# Reload Nginx
sudo systemctl reload nginx

---

Seamless SSH Passthrough on Standard Port 22

By default, the host’s OpenSSH daemon listens on port 22, forcing Gitea’s internal SSH server to run on non-standard port 2222. Developers dislike having to configure custom SSH ports in their clone URLs (ssh://[email protected]:2222/org/repo.git).

We can configure SSH Passthrough. This allows both the system administrator (for VPS maintenance) and software developers (for Git operations) to connect over standard port 22 seamlessly.

Architecture of SSH Passthrough

When an incoming connection arrives at port 22:

1. If the public key belongs to the systems administrator, OpenSSH grants interactive shell access to the host.
2. If the public key belongs to a developer registered in Gitea, OpenSSH routes the request through a small wrapper script (/usr/local/bin/gitea-shell) that proxies the Git commands directly into the Gitea container via docker exec.

Implementation Steps

1. Create a dedicated git user on the host system:

sudo useradd -m -d /home/git -s /bin/bash git || true
sudo mkdir -p /home/git/.ssh
sudo chmod 700 /home/git/.ssh

2. Grant the host git user permission to execute Docker commands inside the Gitea container:

sudo usermod -aG docker git

3. Create the proxy wrapper script /usr/local/bin/gitea-shell:

sudo tee /usr/local/bin/gitea-shell << 'EOF'
#!/bin/sh
docker exec -i --user 1000 gitea_server sh -c "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" gitea serv key-$1 --config=/etc/gitea/app.ini"
EOF

sudo chmod +x /usr/local/bin/gitea-shell

4. Create an SSH key generator script for Gitea’s authorized_keys. Gitea automatically writes developer public keys with forced command directives. Symlink or map the container’s authorized keys file to the host /home/git/.ssh/authorized_keys:

# Symlink authorized_keys from Gitea volume
sudo ln -sf /opt/gitea/data/ssh/authorized_keys /home/git/.ssh/authorized_keys
sudo chown -h git:git /home/git/.ssh/authorized_keys

5. In /opt/gitea/config/app.ini, ensure the SSH root URL is set to standard port 22:

[server]
SSH_DOMAIN       = git.agency.pk
SSH_PORT         = 22
SSH_LISTEN_PORT  = 2222
START_SSH_SERVER = true

Restart Gitea:

cd /opt/gitea && docker compose restart server

Developers can now clone repositories using standard, clean syntax:

git clone [email protected]:client-projects/fintech-backend.git

---

Configuring Gitea Actions (Act Runner) for Local CI/CD

One of Gitea’s most powerful capabilities is Gitea Actions, a native CI/CD engine compatible with GitHub Actions workflow syntax. Engineering teams can run their existing .github/workflows/*.yaml files without rewriting their automation logic.

Step 1: Obtain the Runner Registration Token

1. Log into your Gitea web interface as an administrator.
2. Navigate to Site Administration > Actions > Runners.
3. Click Create new Runner and copy the registration token.

Step 2: Deploy the Act Runner Container

Create a runner directory and configuration:

sudo mkdir -p /opt/gitea-runner
cd /opt/gitea-runner

Create /opt/gitea-runner/docker-compose.yml:

services:
  runner:
    image: gitea/act_runner:latest
    container_name: gitea_act_runner
    restart: always
    environment:
      - GITEA_INSTANCE_URL=https://git.agency.pk
      - GITEA_RUNNER_REGISTRATION_TOKEN=PASTE_YOUR_REGISTRATION_TOKEN_HERE
      - GITEA_RUNNER_NAME=vps-docker-runner-01
      - GITEA_RUNNER_LABELS=ubuntu-latest:docker://catthehacker/ubuntu:act-latest,ubuntu-22.04:docker://catthehacker/ubuntu:act-22.04
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/data

Start the runner:

docker compose up -d

Verify that the runner registers as Active in the Gitea administrative panel.

Step 3: Example GitHub-Compatible CI/CD Workflow

Inside any repository, create .gitea/workflows/build-and-test.yaml:

name: Production CI/CD Pipeline

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Setup Node.js Environment
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install Dependencies
        run: npm ci

      - name: Run Unit & Integration Tests
        run: npm run test:ci

      - name: Build Application Artifacts
        run: npm run build

The pipeline executes entirely on your private VPS, consuming zero paid cloud build minutes and avoiding third-party queue delays.

---

Performance and Storage Optimization

To keep Gitea running at peak responsiveness under sustained load, apply these database, kernel, and filesystem optimizations.

1. PostgreSQL 16 Performance Tuning

By default, PostgreSQL is configured conservatively for low-memory environments. For a VPS with 8 GB RAM, add these directives to your PostgreSQL configuration (/opt/gitea/postgres_data/postgresql.conf):

# Memory Configuration for 8GB Host
shared_buffers = 2GB
effective_cache_size = 6GB
maintenance_work_mem = 512MB
work_mem = 32MB

# Write-Ahead Log (WAL) Tuning
wal_buffers = 16MB
min_wal_size = 1GB
max_wal_size = 4GB
checkpoint_completion_target = 0.9

# Query Planner Optimization for NVMe Storage
random_page_cost = 1.1
effective_io_concurrency = 200

Restart the database container to apply changes:

docker compose restart db

2. Linux Kernel I/O and Network Tuning

Add the following network and memory directives to /etc/sysctl.d/99-gitea.conf:

# Increase socket listen backlog for concurrent Git connections
net.core.somaxconn = 4096

# Expand local port range
net.ipv4.ip_local_port_range = 1024 65535

# Increase file descriptor limits for repository packfiles
fs.file-max = 2097152

# Virtual Memory flushing optimizations for pure NVMe
vm.dirty_background_ratio = 5
vm.dirty_ratio = 10
vm.swappiness = 10

Apply immediately:

sudo sysctl --system

3. Automated Git Garbage Collection (git gc)

Over time, hundreds of developer pushes create loose objects and fragmented commit trees. Schedule automated Git garbage collection across all hosted repositories via Gitea’s built-in cron system in app.ini:

[cron.repo_health_check]
ENABLED = true
SCHEDULE = @weekly

[cron.git_gc_repos]
ENABLED = true
SCHEDULE = @weekly
TIMEOUT = 300s
ARGS = --prune=now --aggressive

---

Automated Disaster Recovery and Off-Site Backups

A self-hosted Git server requires an ironclad, automated disaster recovery pipeline. Relying solely on host VPS snapshots is insufficient; an unquiesced snapshot taken during a heavy database write can result in corrupted PostgreSQL tables or half-written Git packfiles.

Step 1: Automated Cold Dump Script

Gitea provides a native CLI command gitea dump that creates a clean, point-in-time zip archive containing the PostgreSQL database dump, all Git repositories, Git LFS objects, user avatars, attachments, and server configuration files.

Create /opt/scripts/backup-gitea.sh:

#!/usr/bin/env bash
set -euo pipefail

BACKUP_DIR="/opt/gitea/backups"
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
BACKUP_FILENAME="gitea-dump-${TIMESTAMP}.zip"
RETENTION_DAYS=14

mkdir -p "${BACKUP_DIR}"

echo "[$(date)] Starting Gitea automated backup..."

# Execute dump inside Gitea container
docker exec -i --user 1000 gitea_server /usr/local/bin/gitea dump \
  --config /etc/gitea/app.ini \
  --file "/tmp/${BACKUP_FILENAME}"

# Copy archive out to host backup volume
docker cp "gitea_server:/tmp/${BACKUP_FILENAME}" "${BACKUP_DIR}/${BACKUP_FILENAME}"

# Clean up temp file inside container
docker exec -i --user 1000 gitea_server rm -f "/tmp/${BACKUP_FILENAME}"

# Prune local archives older than retention window
find "${BACKUP_DIR}" -type f -name "gitea-dump-*.zip" -mtime +${RETENTION_DAYS} -delete

echo "[$(date)] Backup completed successfully: ${BACKUP_DIR}/${BACKUP_FILENAME}"

Make the script executable:

sudo chmod +x /opt/scripts/backup-gitea.sh

Step 2: Off-Site Cloud Synchronization

Never store backups solely on the host server. Use rclone to push backups to an encrypted S3-compatible cloud storage bucket (e.g., Cloudflare R2, AWS S3, or Backblaze B2) nightly.

Configure a cron job via sudo crontab -e:

# Execute Gitea backup at 02:00 AM daily and sync off-site
0 2 * * * /opt/scripts/backup-gitea.sh && rclone sync /opt/gitea/backups s3-remote:agency-git-backups/gitea/

---

When to Scale: Linux VPS vs. Bare-Metal Dedicated Servers

For most Pakistani software agencies with 10 to 50 engineers, a high-performance Linux VPS delivers exceptional speed and reliability. However, as engineering organizations scale, physical infrastructure constraints begin to surface.

The Virtualization Boundary

1. Multi-Stage CI/CD Docker Builds: When 15 developers merge pull requests simultaneously, triggering 15 concurrent Docker build jobs (compiling TypeScript, building Rust microservices, or running multi-browser Cypress tests), CPU contention on a virtualized VPS can spike CPU steal time.
2. Gigabyte-Scale Git LFS Repositories: Agencies handling game development (Unreal Engine 5 assets, 4K textures) or AI research (storing PyTorch and safetensors model checkpoints) frequently push single commits measuring 5 GB to 20 GB. Shared virtual disks can bottleneck sequential write throughput.
3. Hypervisor Lock Contention: High-frequency Git RPC operations across dozens of concurrent active developers can induce micro-latency in virtualized storage controllers.

Transitioning to Bare-Metal Infrastructure

When your development workforce exceeds 60 to 100 active contributors running intensive continuous integration workloads, upgrading to unshared hardware becomes essential:

• Compute Density & Zero Steal Time: Deploying on enterprise Dedicated Servers provides unshared physical CPU cores (AMD EPYC or Intel Xeon), dedicated NVMe RAID-10 arrays, and unrestricted memory bandwidth. CI/CD test suites run up to 4x faster compared to virtualized environments.
• Sovereign In-Country Infrastructure: For technology vendors catering to Pakistani state institutions, the armed forces, national banks, or telecom operators bound by strict SBP and PTA data localization mandates, deploying on Dedicated Servers in Pakistan guarantees that sensitive client codebases remain physically housed within domestic data centers.

---

Conclusion: Total Autonomy Over Your Engineering Pipeline

Escaping commercial SaaS lock-in is more than a cost-saving measure—it is an investment in your agency’s operational sovereignty, data privacy, and technological resilience.

By self-hosting Gitea on a high-performance Linux VPS:

• You eliminate thousands of dollars in recurring per-seat SaaS licensing fees.
• You bypass credit card foreign transaction limits, currency depreciation, and advance withholding taxes.
• You provide your development team with a lightning-fast, GitHub-compatible environment with native CI/CD Actions and unlimited private repositories.

With proper PostgreSQL tuning, an optimized Nginx reverse proxy, seamless SSH passthrough, and automated off-site backups, Gitea provides enterprise-grade Git hosting with virtually zero maintenance overhead.

---