How To Install Gitea on CentOS Stream 10

Self-hosting your Git repositories has never been more accessible. Gitea offers a lightweight, open-source alternative to platforms like GitHub and GitLab, giving you complete control over your source code management. This comprehensive guide walks you through installing Gitea on CentOS Stream 10, from initial system preparation to securing your new Git service.

Gitea stands out as an efficient solution for development teams seeking a self-hosted Git platform without excessive resource consumption. Unlike heavier alternatives that demand substantial server resources, Gitea operates smoothly on modest hardware while delivering essential features like repository management, issue tracking, pull requests, and built-in wikis. Written in Go, this lightweight platform typically uses less than 120MB of memory and achieves page load times under 100 milliseconds, making it ideal for small to medium-sized teams.

CentOS Stream 10 provides a solid foundation for hosting Gitea, offering enterprise-grade stability with cutting-edge features. This rolling-release distribution serves as the upstream development platform for Red Hat Enterprise Linux, ensuring you benefit from the latest improvements while maintaining production-ready reliability.

Prerequisites

Before proceeding with the Gitea installation, ensure your environment meets these requirements. You need a fresh or existing CentOS Stream 10 server with root or sudo privileges. The system should have at least 2GB of RAM and 2 CPU cores for optimal performance, though Gitea can run on lower specifications for testing purposes.

Allocate between 10GB and 20GB of free disk space to accommodate the Gitea binary, repositories, and associated data. While SQLite works well for small deployments, consider PostgreSQL or MySQL for larger installations handling multiple concurrent users. A stable internet connection is essential for downloading packages and updates during the installation process.

Basic command-line knowledge will help you navigate the terminal and execute commands confidently. If you plan to make your Gitea instance publicly accessible, having a domain name configured with proper DNS records pointing to your server enhances the professional appearance and enables HTTPS configuration.

System Requirements

CentOS Stream 10 introduces specific architectural requirements that differ from previous versions. The operating system requires x86_64-v3 microarchitecture as the minimum supported platform, incorporating kernel 6.12, Python 3.12, and GCC 14 compiler toolchain. These modern components provide enhanced performance and security features.

For Gitea itself, the minimum specifications include a 1 GHz processor, 1GB RAM, and 1GB disk space. However, production environments benefit significantly from upgraded specifications: a 2 GHz dual-core processor, 4GB RAM, and 20GB disk space ensure smooth operation under typical workloads.

Git version 2.0.0 or later must be installed on your system, as Gitea relies on Git for all repository operations. The platform supports multiple database backends including SQLite3 for simple deployments, PostgreSQL for robust performance, and MySQL or MariaDB for compatibility with existing database infrastructure. Network access on ports 3000 (HTTP) and 22 (SSH) enables repository access via web interface and command-line operations.

Step 1: Update Your System

Start by updating all existing packages on your CentOS Stream 10 system. This critical first step ensures you have the latest security patches and software versions before installing new applications.

Open your terminal and execute the following command:

sudo dnf update -y

The DNF package manager will check for available updates and install them automatically. This process may take several minutes depending on your internet connection and the number of pending updates. If kernel updates are installed, reboot your system to apply the changes:

sudo reboot

After the system restarts, verify your CentOS Stream 10 version to confirm you’re running the correct operating system:

cat /etc/centos-release

This command displays the exact CentOS Stream version installed on your server. Regular system updates protect against vulnerabilities and ensure compatibility with modern software packages.

Step 2: Install Required Dependencies

Gitea requires Git and several supporting packages to function properly. Install Git first, as it handles all repository operations:

sudo dnf install git -y

Verify the Git installation by checking the installed version:

git --version

You should see output indicating Git version 2.0 or higher. Next, install SQLite3, which serves as the default database for lightweight Gitea deployments:

sudo dnf install sqlite -y

Install wget for downloading the Gitea binary from the official repository:

sudo dnf install wget -y

For production environments, consider installing additional dependencies like nginx or apache for reverse proxy functionality, and certbot for HTTPS certificate management. These optional packages enhance security and provide professional-grade deployment capabilities.

CentOS Stream 10 includes updated package repositories that ensure all dependencies remain current with the latest security patches and feature improvements.

Step 3: Create a Dedicated Git User

Running Gitea under a dedicated system user follows security best practices by isolating the application from other system processes. This approach limits potential damage if the service becomes compromised.

Create a system user named ‘git’ with appropriate permissions:

sudo groupadd --system git
sudo adduser --system --shell /bin/bash --comment 'Git Version Control' --gid git --home-dir /home/git --create-home git

This command creates a system user with several important characteristics. The --system flag designates this as a service account rather than a regular user account. The --shell /bin/bash parameter provides a functional shell for SSH operations. The --create-home option establishes a home directory where repositories will be stored.

The dedicated git user enhances security by preventing the service from running with elevated privileges. All Gitea processes and data files will belong to this user, creating a clean separation from other system components.

Step 4: Download Gitea Binary

Gitea distributes as a single, self-contained binary that includes all necessary components. This approach simplifies installation and reduces dependency conflicts.

Visit the official Gitea downloads page to identify the latest stable version. At the time of writing, version 1.23.8 represents the current release, but always verify the most recent version before proceeding.

Download the Gitea binary using wget:

export GITEA_VERSION="1.23.8"
wget -O /tmp/gitea https://dl.gitea.com/gitea/${GITEA_VERSION}/gitea-${GITEA_VERSION}-linux-amd64

Move the downloaded binary to the system binaries directory:

sudo mv /tmp/gitea /usr/local/bin/gitea

Make the binary executable:

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

Verify the binary is properly installed:

/usr/local/bin/gitea --version

The output confirms the installed Gitea version and build information. Binary installation provides advantages over source compilation, including faster deployment and consistent behavior across different systems.

Step 5: Create Required Directories

Gitea requires specific directory structures for storing configuration files, repository data, and log files. Proper organization ensures smooth operation and simplifies backup procedures.

Create the primary data directories:

sudo mkdir -p /var/lib/gitea/{custom,data,log}

This single command creates the parent directory and three subdirectories simultaneously. The custom directory stores customization files and templates. The data directory holds repository data and uploaded files. The log directory contains application logs for troubleshooting and monitoring.

Create the configuration directory:

sudo mkdir /etc/gitea

Set appropriate ownership for the data directories:

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

Configure the configuration directory with temporary write permissions:

sudo chown root:git /etc/gitea
sudo chmod 770 /etc/gitea

The temporary write permissions on /etc/gitea allow the web installer to generate the configuration file automatically. After completing the initial setup, you’ll restrict these permissions to enhance security. This approach balances convenience during installation with security best practices for production operation.

Step 6: Configure Systemd Service

Systemd manages Gitea as a system service, ensuring automatic startup and recovery. This configuration enables Gitea to start automatically when the server boots and restart after crashes.

Create a new systemd service file:

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

Add the following configuration:

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

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

[Install]
WantedBy=multi-user.target

This service file defines critical operational parameters. The After=network.target directive ensures Gitea starts only after network services initialize. The RestartSec=2s and Restart=always settings provide automatic recovery from failures. The WorkingDirectory and Environment variables establish the proper execution context.

Save the file and reload the systemd daemon:

sudo systemctl daemon-reload

Enable the Gitea service to start automatically at boot:

sudo systemctl enable gitea

Start the Gitea service:

sudo systemctl start gitea

Verify the service is running properly:

sudo systemctl status gitea

A successful start displays an “active (running)” status with green indicators. If the service fails to start, examine the logs using:

sudo journalctl -u gitea -n 50

This command displays the last 50 log entries, helping identify configuration errors or missing dependencies.

Step 7: Configure Firewall

CentOS Stream 10 includes firewalld for network security management. Opening the necessary ports allows users to access your Gitea installation while maintaining overall system security.

Open port 3000 for HTTP access to the Gitea web interface:

sudo firewall-cmd --permanent --zone=public --add-port=3000/tcp

Ensure SSH access remains available on port 22:

sudo firewall-cmd --permanent --zone=public --add-service=ssh

Reload the firewall configuration to apply changes:

sudo firewall-cmd --reload

Verify the open ports:

sudo firewall-cmd --list-all

The output displays all active firewall rules, confirming ports 3000 and 22 are accessible. These firewall rules balance accessibility with security, allowing legitimate traffic while blocking unauthorized access attempts.

Step 8: Complete Web Installation

Gitea provides a user-friendly web installer that simplifies initial configuration. Access the installer through your web browser.

Open your preferred browser and navigate to:

http://YOUR_SERVER_IP:3000/install

Replace YOUR_SERVER_IP with your actual server IP address or domain name. The installation wizard presents several configuration sections.

Database Settings

Select SQLite3 as the database type for simple deployments. SQLite requires minimal configuration and works well for small to medium teams. Set the database path to:

/var/lib/gitea/data/gitea.db

For larger deployments, choose PostgreSQL or MySQL and provide the appropriate connection details including hostname, port, database name, username, and password.

Application General Settings

Configure the following parameters:

Site Title: Enter a descriptive name for your Gitea instance, such as “Company Git Server” or “Development Repository.”

Repository Root Path: Keep the default /home/git/gitea-repositories where all Git repositories will be stored.

Git LFS Root Path: Maintain the default /var/lib/gitea/data/lfs for Large File Storage support.

Run As Username: Confirm this shows git, matching the system user created earlier.

SSH Server Domain: Enter your domain name or server IP address for SSH clone operations.

SSH Port: Use 22 for standard SSH access, or specify a custom port if you’ve configured SSH differently.

Gitea HTTP Listen Port: Keep the default 3000 for the web interface.

Gitea Base URL: Set this to http://YOUR_DOMAIN_OR_IP:3000 using your actual domain or IP address.

Log Path: Maintain the default /var/lib/gitea/log for application logs.

Optional Settings

Expand the optional settings section to configure email notifications, enable user registration, require sign-in to view pages, and adjust other preferences according to your requirements.

After reviewing all settings, click the “Install Gitea” button. The installer creates the configuration file and initializes the database. This process typically completes within seconds.

Upon successful installation, you’ll be redirected to the login page. Click “Register” to create the first user account. This initial user automatically receives administrator privileges, granting full control over the Gitea instance.

Step 9: Secure Configuration File

After completing the web installation, restrict configuration file permissions to prevent unauthorized modifications. This critical security step protects sensitive information stored in the configuration.

Change the /etc/gitea directory permissions to read-only:

sudo chmod 750 /etc/gitea

Restrict the configuration file itself:

sudo chmod 640 /etc/gitea/app.ini

These permission changes ensure only the root user can modify configuration settings while allowing the git user to read necessary parameters. Restart the Gitea service to verify it operates correctly with the new permissions:

sudo systemctl restart gitea
sudo systemctl status gitea

The service should restart without errors, confirming the permission changes don’t interfere with normal operation.

(Optional) Step 10: Configure Nginx Reverse Proxy

Implementing a reverse proxy enhances security, enables HTTPS, and provides professional URL structure without port numbers. Nginx excels at this role with minimal resource consumption.

Install Nginx:

sudo dnf install nginx -y

Create a new Nginx configuration file for Gitea:

sudo nano /etc/nginx/conf.d/gitea.conf

Add the following configuration:

server {
    listen 80;
    server_name your-domain.com;

    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;
    }
}

Replace your-domain.com with your actual domain name. Test the Nginx configuration:

sudo nginx -t

Enable and start Nginx:

sudo systemctl enable nginx
sudo systemctl start nginx

Update firewall rules to allow HTTP and HTTPS traffic:

sudo firewall-cmd --permanent --zone=public --add-service=http
sudo firewall-cmd --permanent --zone=public --add-service=https
sudo firewall-cmd --reload

Edit /etc/gitea/app.ini and update the ROOT_URL to remove the port number:

[server]
ROOT_URL = http://your-domain.com/

Restart Gitea to apply changes:

sudo systemctl restart gitea

Now users can access your Gitea instance without specifying port 3000 in the URL.

(Optional) Step 11: Enable HTTPS with Let’s Encrypt

HTTPS encryption protects sensitive data transmitted between users and your Gitea server. Let’s Encrypt provides free SSL certificates with automated renewal.

Install Certbot and the Nginx plugin:

sudo dnf install certbot python3-certbot-nginx -y

Obtain an SSL certificate for your domain:

sudo certbot --nginx -d your-domain.com

Certbot will ask for your email address and agreement to terms of service. It automatically configures Nginx for HTTPS and sets up certificate renewal.

Update the Gitea configuration to reflect HTTPS:

sudo nano /etc/gitea/app.ini

Modify the ROOT_URL in the [server] section:

[server]
ROOT_URL = https://your-domain.com/

Keep PROTOCOL = http and HTTP_PORT = 3000 unchanged, as Nginx handles SSL termination. Restart Gitea:

sudo systemctl restart gitea

Verify automatic certificate renewal:

sudo certbot renew --dry-run

Your Gitea instance now operates securely over HTTPS with automatic certificate renewal every 90 days.

(Optional) Step 12: Configure Email Notifications

Email notifications keep team members informed about repository activity, pull requests, and issues. Configure SMTP settings to enable this functionality.

Edit the Gitea configuration file:

sudo nano /etc/gitea/app.ini

Add or modify the [mailer] section:

[mailer]
ENABLED = true
FROM = noreply@your-domain.com
MAILER_TYPE = smtp
HOST = smtp.your-provider.com:587
IS_TLS_ENABLED = true
USER = your-smtp-username
PASSWD = your-smtp-password

Replace the values with your actual SMTP server details. Popular SMTP providers include SendGrid, Mailgun, Amazon SES, and your organization’s mail server.

Restart Gitea to apply email settings:

sudo systemctl restart gitea

Test email functionality by registering a new user or triggering a notification. Check the Gitea logs if emails fail to send:

sudo tail -f /var/lib/gitea/log/gitea.log

Verifying Gitea Installation

Confirm your Gitea installation functions correctly by testing core features. Access the web interface through your configured URL and log in with your administrator account.

Create a test repository by clicking the plus icon in the top-right corner and selecting “New Repository.” Provide a repository name, description, and visibility settings, then click “Create Repository.”

Clone the repository to your local machine using HTTPS:

git clone https://your-domain.com/username/test-repo.git

Or via SSH after adding your SSH public key to your Gitea profile:

git clone git@your-domain.com:username/test-repo.git

Create a test file, commit, and push changes:

cd test-repo
echo "# Test Repository" > README.md
git add README.md
git commit -m "Initial commit"
git push origin main

Refresh the repository page in your browser to confirm the changes appear. Test additional features including issue creation, wiki pages, and user management to verify complete functionality.

Basic Gitea Configuration and Usage

The Gitea admin panel provides comprehensive control over your Git platform. Access it by clicking your avatar and selecting “Site Administration.” Here you can manage users, organizations, repositories, and system settings.

User management includes creating accounts, assigning permissions, and configuring authentication methods. Organizations group related projects and team members, simplifying permission management for collaborative development.

Repository settings control visibility (public, private, or internal), enable features like issue tracking and pull requests, and configure webhooks for integration with CI/CD pipelines. SSH key management allows users to add public keys for secure, password-free authentication.

Understanding the Git workflow with Gitea enhances productivity. Developers clone repositories, create branches for features, commit changes regularly, and submit pull requests for code review. Team leads review proposed changes, provide feedback, and merge approved modifications into the main branch.

Security Hardening Best Practices

Securing your Gitea installation protects valuable source code and maintains user trust. Implement multiple security layers for comprehensive protection.

Enable two-factor authentication (2FA) for all administrative accounts. Navigate to Settings > Security > Two-Factor Authentication and follow the prompts to configure TOTP-based authentication using apps like Google Authenticator or Authy.

Configure regular automated backups of the /var/lib/gitea/data directory and /etc/gitea/app.ini configuration file. Store backups in a separate location or remote system to protect against hardware failure or ransomware.

Disable new user registration if operating a private instance. Navigate to Site Administration > Configuration and modify authentication settings to require administrator approval for new accounts.

Monitor system logs regularly for suspicious activity:

sudo journalctl -u gitea -f

Watch for repeated failed login attempts, unusual access patterns, or error messages indicating security probes. Consider implementing fail2ban to automatically block IP addresses exhibiting suspicious behavior.

Keep Gitea updated with the latest security patches by subscribing to the project’s security announcements and applying updates promptly when released.

Troubleshooting Common Issues

Even carefully executed installations occasionally encounter problems. These troubleshooting strategies resolve common issues quickly.

If Gitea fails to start, examine the service logs:

sudo journalctl -u gitea -n 100 --no-pager

Permission errors typically indicate incorrect ownership or access rights on critical directories. Verify all data directories belong to the git user:

sudo ls -la /var/lib/gitea/
sudo ls -la /etc/gitea/

Database connection failures suggest incorrect credentials or network issues. Verify database settings in /etc/gitea/app.ini match your database server configuration.

Firewall blockages prevent users from accessing the web interface. Confirm port 3000 (or 80/443 if using a reverse proxy) is open:

sudo firewall-cmd --list-ports
sudo netstat -tlnp | grep gitea

SSH clone issues often stem from key management problems. Ensure users have correctly added their public SSH keys to their Gitea profiles and can authenticate:

ssh -T git@your-domain.com

Performance problems on active instances may require resource adjustments. Monitor system resources and consider upgrading RAM or CPU allocation if sustained high utilization occurs.

Upgrading Gitea

Keeping Gitea current ensures access to new features, performance improvements, and security fixes. The upgrade process mirrors the initial installation with added precautions.

Before upgrading, create comprehensive backups:

sudo systemctl stop gitea
sudo tar -czf /tmp/gitea-backup-$(date +%Y%m%d).tar.gz /var/lib/gitea/ /etc/gitea/

Download the latest Gitea binary:

export NEW_VERSION="1.24.0"
wget -O /tmp/gitea-new https://dl.gitea.com/gitea/${NEW_VERSION}/gitea-${NEW_VERSION}-linux-amd64

Replace the existing binary:

sudo mv /tmp/gitea-new /usr/local/bin/gitea
sudo chmod +x /usr/local/bin/gitea

Start Gitea and verify the upgrade:

sudo systemctl start gitea
/usr/local/bin/gitea --version

Check the web interface and test critical functionality to ensure the upgrade completed successfully. Review the Gitea changelog for breaking changes or new configuration options requiring attention.

Congratulations! You have successfully installed Gitea. Thanks for using this tutorial for installing Gitea management of repositories based Git on CentOS Stream 10 Linux systems. For additional help or useful information, we recommend you check the official Gitea website.