How To Install Gitea on Debian 13

Gitea stands as one of the most compelling self-hosted Git solutions available today, offering developers and organizations a lightweight, secure alternative to commercial platforms like GitHub and GitLab. This comprehensive guide will walk you through the complete process of installing Gitea on Debian 13, ensuring you have a fully functional, production-ready Git hosting service.

Whether you’re a developer seeking greater control over your repositories, an organization prioritizing data privacy, or a team looking for cost-effective version control hosting, Gitea provides the perfect balance of functionality and simplicity. Unlike resource-heavy alternatives, Gitea operates efficiently on modest hardware while delivering enterprise-grade features including issue tracking, pull requests, project management, and integrated CI/CD capabilities.

This tutorial targets system administrators, DevOps engineers, and developers with basic Linux command-line experience. You’ll learn not only how to install Gitea but also how to secure, configure, and maintain your installation for optimal performance and reliability.

Prerequisites and System Requirements

Before diving into the installation process, ensure your Debian 13 system meets the necessary requirements for a smooth Gitea deployment.

Hardware Requirements

Gitea’s lightweight design makes it suitable for various deployment scenarios. For basic installations serving small teams (up to 10 users), allocate at least 1GB RAM, 1 CPU core, and 10GB storage space. Production environments supporting larger teams require 2GB RAM minimum, 2 CPU cores, and storage scaling based on repository size expectations.

Consider that Git repositories can grow significantly over time, especially when storing large binary files. Plan for at least 50GB initial storage with expansion capabilities for long-term sustainability.

Software Prerequisites

Your Debian 13 server must have a fresh installation with root or sudo access. Ensure SSH connectivity is properly configured for remote administration. A stable internet connection is essential for downloading packages and accessing external resources during setup.

Network requirements include availability of port 3000 for Gitea’s web interface, though this can be customized during configuration. If you plan to implement HTTPS immediately, ensure port 443 is accessible and consider obtaining an SSL certificate before beginning installation.

Technical Knowledge Requirements

This guide assumes familiarity with basic Linux system administration, including file editing, service management, and command-line navigation. While we’ll provide detailed instructions, understanding concepts like user permissions, systemd services, and database administration will prove beneficial.

Optional but recommended components include a domain name for professional access, reverse proxy knowledge for advanced configurations, and backup strategies for data protection.

System Preparation and Initial Setup

Proper system preparation forms the foundation of a stable Gitea installation. Begin by updating your Debian 13 system to ensure all packages reflect the latest security patches and improvements.

Updating the System

Execute the following commands to refresh package repositories and upgrade existing software:

sudo apt update && sudo apt upgrade -y

This process may take several minutes depending on your system’s current state and available updates. Reboot if kernel updates were installed to ensure all changes take effect properly.

Installing Essential Dependencies

Gitea requires several system packages for optimal functionality. Install the necessary dependencies using:

sudo apt install -y git curl wget software-properties-common gnupg2 ca-certificates

These packages provide essential tools for downloading Gitea, managing repositories, and maintaining secure connections. The git package enables repository operations, while curl and wget facilitate file downloads during installation and maintenance.

Security Hardening Preparation

Configure your system’s firewall using UFW (Uncomplicated Firewall) to control network access:

sudo ufw enable
sudo ufw allow ssh
sudo ufw allow 3000/tcp

This configuration permits SSH access for administration while opening port 3000 for Gitea’s web interface. Additional ports may be required depending on your specific setup requirements.

Create a system backup or snapshot before proceeding with the installation. This precaution enables quick recovery if unexpected issues arise during the setup process.

Database Setup and Configuration

Gitea supports multiple database backends, each offering distinct advantages depending on your deployment scenario and performance requirements.

Choosing the Right Database Backend

SQLite provides the simplest setup option, requiring no additional configuration or maintenance. This file-based database works excellently for small teams and development environments with moderate usage patterns. SQLite eliminates database server overhead while maintaining ACID compliance and reliable performance.

MariaDB delivers superior performance for production environments expecting heavy usage or multiple concurrent users. This MySQL-compatible database offers advanced features including replication, clustering, and comprehensive backup solutions. MariaDB scales effectively as your Gitea instance grows.

PostgreSQL represents the most feature-rich option, providing advanced data types, full-text search capabilities, and excellent concurrent performance. Choose PostgreSQL for enterprise deployments requiring sophisticated database features or complex querying capabilities.

MariaDB Installation and Configuration

For production deployments, MariaDB offers the optimal balance of performance and reliability. Install MariaDB server and client components:

sudo apt install -y mariadb-server mariadb-client

Secure your MariaDB installation using the included security script:

sudo mysql_secure_installation

Follow the prompts to set a strong root password, remove anonymous users, disable remote root login, and delete test databases. These steps significantly improve your database security posture.

Creating Gitea Database and User

Access the MariaDB command line interface and create a dedicated database and user for Gitea:

sudo mysql -u root -p

Execute the following SQL commands within the MariaDB shell:

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

Replace your_secure_password with a strong, unique password. Record these credentials securely as they’ll be required during Gitea configuration.

Test database connectivity to ensure proper setup:

mysql -u gitea -p -D gitea

Successfully connecting confirms your database configuration is ready for Gitea integration.

User Management and Directory Structure

Security best practices mandate running Gitea under a dedicated system user with minimal privileges. This approach limits potential security exposure and simplifies permission management.

Creating the Gitea System User

Create a dedicated system user for Gitea operations:

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

This command creates a system user named git with a home directory at /home/git. The user cannot login directly, enhancing security while providing necessary functionality for Git operations.

Establishing Directory Structure

Create essential directories for Gitea operation with proper ownership:

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

This structure separates configuration, data, and logs into appropriate locations following Linux filesystem hierarchy standards. The /var/lib/gitea/custom directory stores user customizations, /var/lib/gitea/data contains repositories and application data, while /var/lib/gitea/log holds application logs.

Setting Proper Permissions

Configure directory permissions to balance security with functionality:

sudo chmod 750 /var/lib/gitea/
sudo chmod 750 /var/lib/gitea/data
sudo chmod 750 /var/lib/gitea/log

These permissions allow the git user full access while preventing unauthorized access from other system users. Proper permission management is crucial for maintaining security in multi-user environments.

Downloading and Installing Gitea Binary

Gitea distributes as a single binary file, simplifying installation and reducing dependencies compared to complex multi-component applications.

Determining the Latest Version

Visit the official Gitea releases page or use the GitHub API to identify the current stable version. As of this writing, check for the latest release using:

curl -s https://api.github.com/repos/go-gitea/gitea/releases/latest | grep "tag_name"

Alternatively, manually check the official Gitea releases page for the most current version information.

Downloading the Gitea Binary

Download the appropriate Gitea binary for your system architecture. For most Debian 13 installations on x86_64 systems:

wget -O gitea https://dl.gitea.com/gitea/1.24.5/gitea-1.24.5-linux-amd64

Replace the version number with the latest available release. For ARM-based systems, substitute linux-amd64 with the appropriate architecture identifier such as linux-arm64.

Verifying Download Integrity

Security-conscious administrators should verify download integrity using provided checksums:

wget https://dl.gitea.io/gitea/1.21.0/gitea-1.24.5-linux-amd64.sha256
sha256sum -c gitea-1.24.5-linux-amd64.sha256

Successful verification confirms the download hasn’t been tampered with during transit.

Installing to System Path

Move the Gitea binary to the system path and set appropriate permissions:

sudo cp gitea /usr/local/bin/gitea
sudo chmod +x /usr/local/bin/gitea

Verify the installation by checking the Gitea version:

gitea --version

This command should display version information, confirming successful binary installation.

Gitea Configuration and Setup

Gitea’s configuration file controls all aspects of application behavior, from database connections to security policies and user interface customization.

Creating the Initial Configuration

Switch to the git user and create the primary configuration file:

sudo -u git /usr/local/bin/gitea web -c /etc/gitea/app.ini --pid /var/run/gitea.pid

This initial run generates a basic configuration template. Stop the process using Ctrl+C after it starts successfully.

Create a comprehensive configuration file at /etc/gitea/app.ini:

[database]
DB_TYPE = mysql
HOST = 127.0.0.1:3306
NAME = gitea
USER = gitea
PASSWD = your_secure_password

[repository]
ROOT = /var/lib/gitea/data/gitea-repositories

[server]
DOMAIN = your-domain.com
HTTP_PORT = 3000
ROOT_URL = http://your-domain.com:3000/
DISABLE_SSH = false
SSH_PORT = 22

[security]
INSTALL_LOCK = false
SECRET_KEY = generate_a_secret_key_here

[service]
DISABLE_REGISTRATION = false
REQUIRE_SIGNIN_VIEW = false

[log]
MODE = file
LEVEL = Info
ROOT_PATH = /var/lib/gitea/log

Replace placeholder values with your specific configuration details. Generate a secure secret key using:

openssl rand -base64 32

Advanced Configuration Options

Gitea offers extensive customization through additional configuration sections. Repository settings control default branch names, size limits, and enabled features:

[repository]
DEFAULT_BRANCH = main
MAX_CREATION_LIMIT = 100
DISABLE_HTTP_GIT = false
USE_COMPAT_SSH_URI = false

User registration policies determine how new users can access your Gitea instance:

[service]
DISABLE_REGISTRATION = true
ALLOW_ONLY_EXTERNAL_REGISTRATION = false
REQUIRE_SIGNIN_VIEW = true
DEFAULT_KEEP_EMAIL_PRIVATE = true

Email configuration enables notifications and account verification:

[mailer]
ENABLED = true
HOST = smtp.example.com:587
FROM = gitea@example.com
USER = gitea@example.com
PASSWD = email_password

Systemd Service Creation and Management

Systemd integration ensures Gitea starts automatically during system boot and provides standard service management capabilities.

Creating the Service File

Create a systemd service file at /etc/systemd/system/gitea.service:

[Unit]
Description=Gitea (Git with a cup of tea)
After=syslog.target
After=network.target
After=mysql.service

[Service]
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea/
RuntimeDirectory=gitea
RuntimeDirectoryMode=755
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini --pid /run/gitea/gitea.pid
Restart=always
RestartSec=10
Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea

[Install]
WantedBy=multi-user.target

This configuration ensures Gitea starts after essential services and automatically restarts if it crashes.

Enabling and Starting the Service

Reload systemd configuration and enable the Gitea service:

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

Verify service status using:

sudo systemctl status gitea

A successful start displays “Active (running)” status with recent log entries.

Service Management Commands

Common service management operations include:

# Start the service
sudo systemctl start gitea

# Stop the service
sudo systemctl stop gitea

# Restart the service
sudo systemctl restart gitea

# Check service status
sudo systemctl status gitea

# View service logs
sudo journalctl -u gitea -f

Monitor service logs during initial setup to identify and resolve any configuration issues promptly.

Web Interface Initial Setup

Gitea’s web-based setup wizard simplifies initial configuration, allowing you to complete installation through an intuitive interface.

Accessing the Web Interface

Open your web browser and navigate to http://your-server-ip:3000 or http://your-domain.com:3000. The initial setup page should load, presenting database configuration options and administrative settings.

Completing Database Configuration

The setup wizard pre-populates database settings based on your configuration file. Verify the database connection details match your MariaDB setup:

• Database Type: MySQL
• Host: 127.0.0.1:3306
• Username: gitea
• Password: your_secure_password
• Database Name: gitea

Click “Test Connection” to verify database connectivity before proceeding.

Administrator Account Creation

Create your initial administrator account using a strong username and password combination. This account will have full system privileges including user management, organization creation, and system configuration access.

Provide a valid email address for account recovery and notifications. Consider using a dedicated administrative email address rather than personal accounts for professional deployments.

Site Configuration

Configure basic site settings including:

• Site Title: Your organization or project name
• Repository Root Path: /var/lib/gitea/data/gitea-repositories
• Git LFS Root Path: /var/lib/gitea/data/lfs
• Run User: git
• SSH Server Domain: your-domain.com
• HTTP Port: 3000

Review all settings carefully before clicking “Install Gitea” to complete the setup process.

Security Hardening and Best Practices

Production Gitea deployments require additional security measures beyond basic installation to protect against common threats and unauthorized access.

Network Security Implementation

Configure UFW firewall rules to restrict access appropriately:

sudo ufw limit ssh
sudo ufw allow 3000/tcp
sudo ufw deny 3000/tcp from 192.168.1.0/24
sudo ufw allow from trusted_ip to any port 3000

These rules limit SSH connection attempts, allow general HTTP access to Gitea, but restrict access from specific network ranges or allow only trusted IP addresses.

Reverse Proxy Configuration

Implement Nginx as a reverse proxy for SSL termination and improved security. Install Nginx:

sudo apt install -y nginx

Create a virtual host configuration at /etc/nginx/sites-available/gitea:

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $http_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 configuration and restart Nginx:

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

SSL Certificate Installation

Secure your Gitea installation using Let’s Encrypt certificates:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

This process automatically configures SSL and updates your Nginx configuration for HTTPS support.

Application Security Settings

Update your Gitea configuration to enhance application security:

[security]
INSTALL_LOCK = true
SECRET_KEY = your_generated_secret_key
PASSWORD_HASH_ALGO = pbkdf2
MIN_PASSWORD_LENGTH = 8
PASSWORD_COMPLEXITY = lower,upper,digit,spec

[service]
DISABLE_REGISTRATION = true
REQUIRE_SIGNIN_VIEW = true
DEFAULT_KEEP_EMAIL_PRIVATE = true
ENABLE_NOTIFY_MAIL = true

These settings lock the installation wizard, enforce strong passwords, disable public registration, and require authentication for repository access.

Post-Installation Configuration and Optimization

With Gitea successfully installed and secured, focus on optimization and user experience enhancements to maximize productivity and system performance.

Creating Your First Repository

Test Gitea functionality by creating a test repository through the web interface. Click the “+” icon and select “New Repository.” Configure repository settings including name, description, visibility, and initialization options.

Clone the repository using Git to verify SSH and HTTPS connectivity:

git clone http://your-domain.com:3000/username/repository.git

Successful cloning confirms proper Gitea configuration and network connectivity.

User Management and Organization Setup

Access the Site Administration panel to manage users, organizations, and system-wide settings. Create organizations for project grouping and team collaboration. Configure user groups with appropriate repository access permissions.

Enable two-factor authentication for administrator accounts through user settings. This additional security layer protects against password-based attacks and unauthorized access.

Integration and Automation

Configure webhooks to integrate Gitea with continuous integration systems, issue trackers, and communication platforms. Access repository settings and navigate to the Webhooks section to add external integrations.

Popular integrations include:

• Jenkins for continuous integration
• Discord/Slack for team notifications
• Jira for issue tracking synchronization
• Docker Hub for automated container builds

Performance Optimization

Monitor system resource usage and optimize Gitea performance through configuration tuning:

[server]
LFS_START_SERVER = true
OFFLINE_MODE = false

[cache]
ADAPTER = memory
INTERVAL = 60

[session]
PROVIDER = file
PROVIDER_CONFIG = /var/lib/gitea/data/sessions

Enable Git LFS for large file handling, configure caching for improved response times, and optimize session management for better user experience.

Maintenance and Troubleshooting

Regular maintenance ensures optimal Gitea performance and prevents common issues that could impact user productivity or system stability.

Routine Maintenance Tasks

Implement log rotation to prevent disk space exhaustion:

sudo nano /etc/logrotate.d/gitea

Add the following configuration:

/var/lib/gitea/log/*.log {
    daily
    missingok
    rotate 52
    compress
    notifempty
    create 640 git git
    postrotate
        systemctl reload gitea
    endscript
}

Monitor repository growth and disk usage regularly:

du -sh /var/lib/gitea/data/gitea-repositories/
df -h

Database Maintenance

Perform regular database optimization for MariaDB installations:

sudo mysql -u root -p

Execute within the MariaDB shell:

USE gitea;
OPTIMIZE TABLE repository;
OPTIMIZE TABLE user;
ANALYZE TABLE repository;
ANALYZE TABLE user;

Backup Strategies

Implement comprehensive backup procedures covering both database and repository data:

#!/bin/bash
# Gitea backup script
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/var/backups/gitea"

# Create backup directory
mkdir -p $BACKUP_DIR

# Dump database
mysqldump -u gitea -p gitea > $BACKUP_DIR/gitea_db_$DATE.sql

# Backup repositories and data
tar -czf $BACKUP_DIR/gitea_data_$DATE.tar.gz -C /var/lib/gitea data

# Backup configuration
cp /etc/gitea/app.ini $BACKUP_DIR/app.ini_$DATE

# Remove backups older than 30 days
find $BACKUP_DIR -name "*.sql" -mtime +30 -delete
find $BACKUP_DIR -name "*.tar.gz" -mtime +30 -delete

Common Troubleshooting Issues

Service startup failures typically result from configuration errors or permission problems. Check service logs using:

sudo journalctl -u gitea -n 50

Database connection errors often indicate incorrect credentials or database service issues. Verify MariaDB status and connection parameters:

sudo systemctl status mariadb
mysql -u gitea -p -e "SELECT 1;"

Permission problems manifest as file access errors or repository operation failures. Reset permissions using:

sudo chown -R git:git /var/lib/gitea/
sudo chmod -R 750 /var/lib/gitea/

Upgrading and Updates

Maintaining current Gitea versions ensures access to latest features, security patches, and performance improvements while minimizing vulnerability exposure.

Planning Your Upgrade Strategy

Before upgrading, create comprehensive backups including database dumps, repository data, and configuration files. Plan maintenance windows during low-usage periods to minimize user impact.

Review release notes for breaking changes, new features, and migration requirements. Some upgrades may require database schema updates or configuration modifications.

Performing the Upgrade

Stop the Gitea service and backup current installation:

sudo systemctl stop gitea
sudo cp /usr/local/bin/gitea /usr/local/bin/gitea.backup

Download and install the new version:

wget -O gitea-new https://dl.gitea.io/gitea/1.22.0/gitea-1.22.0-linux-amd64
sudo cp gitea-new /usr/local/bin/gitea
sudo chmod +x /usr/local/bin/gitea

Start Gitea and monitor for proper operation:

sudo systemctl start gitea
sudo systemctl status gitea
sudo journalctl -u gitea -f

Post-Upgrade Verification

Test critical functionality including repository access, user authentication, and administrative functions. Verify integrations and webhooks continue operating correctly.

If issues arise, rollback using the backup binary:

sudo systemctl stop gitea
sudo cp /usr/local/bin/gitea.backup /usr/local/bin/gitea
sudo systemctl start gitea

Congratulations! You have successfully installed Gitea. Thanks for using this tutorial for installing Gitea on your Debian 13 “Trixie” system. For additional help or useful information, we recommend you check the official Gitea website.