Migrating Gitea to a New Linux VPS: Part 1 - Planning and Pre-Migration Assessment

Sanjaya Subedi

15 Jan 2026 • 6 min read

Introduction

Migrating a production Gitea instance is a critical operation that requires careful planning and execution. In this multi-part series, I'll walk you through the complete process of migrating Gitea from a Windows Hyper-V environment to a fresh Linux VPS in your data center.

This first installment focuses on assessment, planning, and preparing your target environment. By the end of this guide, you'll have a clear migration strategy and a properly hardened Linux server ready to receive your Gitea installation.

Understanding the Migration Challenge

Gitea migrations involve several interconnected components:

Application binaries and configuration: The Gitea executable and its app.ini configuration file
Git repositories: All repository data, including branches, tags, and commit history
Database: User accounts, permissions, organizations, issues, pull requests, and metadata
Attachments and LFS objects: Files uploaded to issues, releases, and Git LFS storage
Custom hooks and integrations: Pre-receive, post-receive, and other Git hooks
SSH keys and authentication: User SSH keys and authentication configurations

The good news is that Gitea is designed to be portable. Unlike some version control systems, Gitea stores everything in well-defined locations, making migrations straightforward when done methodically.

Phase 1: Pre-Migration Assessment

Documenting the Source Environment

Before touching anything, thoroughly document your existing Gitea setup:

1. Gitea Version and Configuration

SSH or RDP into your current Gitea server and gather:

# Check Gitea version
gitea --version

# Locate the configuration file (typically /etc/gitea/app.ini or custom path)
# On Windows, check C:\gitea\custom\conf\app.ini or similar

# Note the working directory
ps aux | grep gitea  # Linux
# Or check service properties on Windows

2. Database Details

Identify your database backend:

Database type (MySQL, PostgreSQL, SQLite, MSSQL)
Database version
Database size (you'll need this for capacity planning)
Connection details from app.ini

3. Storage Locations

Document where Gitea stores data:

Repository root path (REPO_ROOT in app.ini)
Data directory (APP_DATA_PATH)
Attachment storage
LFS storage location (if enabled)
Custom avatars and assets

4. Network Configuration

Record current settings:

Domain name or IP address
HTTP/HTTPS ports
SSH port for Git operations
Reverse proxy configuration (if any)
SSL/TLS certificate details

5. Usage Metrics

Understanding your workload helps with capacity planning:

Number of repositories
Number of users and organizations
Total storage consumed
Average daily Git operations
Peak usage times

Estimating Downtime Requirements

For a typical Gitea migration, expect:

Small installations (<50 repos, <5GB): 30-60 minutes
Medium installations (50-500 repos, 5-50GB): 1-3 hours
Large installations (>500 repos, >50GB): 3-8 hours

The database restore and repository transfer are usually the longest steps.

Phase 2: Target Environment Preparation

Setting Up Your New Linux VPS

For this migration, I recommend Ubuntu 22.04 LTS or 24.04 LTS for their stability and long-term support. The initial server setup is crucial for security and reliability.

Initial Server Hardening

Follow the comprehensive Ubuntu setup guides from SecNep for a production-ready foundation:

Basic Security and System Configuration: Ubuntu Setup Guide Part I covers essential first steps including:
- Initial user setup and SSH key authentication
- Disabling password authentication
- Firewall configuration with UFW
- Automatic security updates
- Timezone and locale configuration
Advanced Hardening: Ubuntu Setup Part II provides additional security layers:
- Fail2ban configuration for intrusion prevention
- Additional SSH hardening
- System monitoring basics
- Log management

These guides will give you a solid, secure foundation. Complete both before proceeding with Gitea-specific setup.

Additional Gitea-Specific Preparations

After completing the base Ubuntu setup, make these Gitea-specific preparations:

1. Install Required Dependencies

sudo apt update
sudo apt install -y git curl wget sudo

# If using PostgreSQL (recommended for production)
sudo apt install -y postgresql postgresql-contrib

# If using MySQL/MariaDB
sudo apt install -y mariadb-server mariadb-client

2. Create Gitea System User

# Create a dedicated user for Gitea
sudo adduser --system --group --disabled-password --shell /bin/bash --home /home/git git

# Create necessary directories
sudo mkdir -p /var/lib/gitea/{custom,data,log}
sudo mkdir -p /etc/gitea
sudo chown -R git:git /var/lib/gitea
sudo chown root:git /etc/gitea
sudo chmod 750 /etc/gitea

3. Prepare the Database

# Switch to postgres user
sudo -u postgres psql

# Inside PostgreSQL prompt:
CREATE DATABASE gitea;
CREATE USER gitea WITH PASSWORD 'your-secure-password-here';
GRANT ALL PRIVILEGES ON DATABASE gitea TO gitea;
\q

For MySQL/MariaDB:

sudo mysql -u root -p

# Inside MySQL prompt:
CREATE DATABASE gitea CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_unicode_ci';
CREATE USER 'gitea'@'localhost' IDENTIFIED BY 'your-secure-password-here';
GRANT ALL PRIVILEGES ON gitea.* TO 'gitea'@'localhost';
FLUSH PRIVILEGES;
EXIT;

4. Configure Firewall Rules

# Allow HTTP/HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Allow SSH for Git (default port 22, or custom port)
sudo ufw allow 22/tcp

# If using a custom SSH port for Gitea, allow it too
# sudo ufw allow 2222/tcp

# Verify rules
sudo ufw status

Capacity Planning

Based on your source environment assessment, ensure your new VPS has:

CPU: Minimum 2 cores; 4+ cores for >100 active users

RAM:

Small (<50 repos): 2GB minimum, 4GB recommended
Medium (50-500 repos): 4GB minimum, 8GB recommended
Large (>500 repos): 8GB minimum, 16GB+ recommended

Storage:

Current Gitea data size × 2 (for growth)
Consider SSD storage for database performance
Separate volume for repositories if possible

Bandwidth: Ensure adequate bandwidth for repository cloning and pushing during and after migration

Pre-Migration Checklist

Before proceeding to the migration planning and execution (covered in Part 2), verify:

Source environment fully documented
Target VPS provisioned and hardened per Ubuntu setup guides
Database installed and configured on target
Gitea system user and directories created
Firewall rules configured
Capacity requirements met
Backup of source system confirmed and tested

What's Next

In Part 2 of this series, we'll develop a comprehensive migration plan and execute the actual migration:

Creating a detailed migration timeline and strategy
Backup procedures for the source Gitea instance
Data transfer methods and best practices
Database migration techniques
Installing and configuring Gitea on the target Linux server
Repository restoration and validation
Testing procedures and rollback strategies

Part 3 will cover post-migration tasks:

Setting up a reverse proxy with SSL/TLS
Configuring SSH access for Git operations
DNS cutover procedures
Post-migration validation and testing
Performance optimization
User communication and support

Conclusion

A successful Gitea migration begins with a rock-solid foundation. In this first part, we've focused on understanding what needs to be migrated and preparing a secure, properly configured target environment. By taking the time to thoroughly document your source environment and build a hardened Ubuntu server, you're setting yourself up for a smooth migration with minimal risk.

The security hardening and system configuration steps we've covered here aren't just checkboxes—they're essential to ensuring your new Gitea instance will be reliable, secure, and performant from day one. A production Git server handles your organization's most critical asset (your source code), so cutting corners on the foundation is never worth the risk.

With your target environment now ready, you're prepared to move on to the migration planning and execution phase. In the next installment, we'll roll up our sleeves and walk through the complete migration process step by step.

To learn about system setup after initialization you can browse here: