How to Install and Use Gitea

Technical writer

Git

28.06.2024

Reading time: 13 min

Gitea is a lightweight and accessible version control system based on Git, designed for ease and efficiency for both individual users and teams. The platform is open source, making it freely available for use and modification. The main advantage of Gitea is that it can be deployed on a user's private server, ensuring complete control over data and configuration.

Gitea offers all the essential Git features, such as branching, merging, and tagging, as well as additional project management conveniences, including a task tracking system, wiki pages, and code review tools. This makes it an ideal solution for development teams who want to collaborate on projects in an isolated and secure environment.

As more organizations and individuals recognize the importance of digital security and autonomy, Gitea stands out as a reliable and convenient solution for self-managing data and projects. An active community and extensive documentation further simplify the adoption and use of this system in various contexts.

Version control systems are traditionally associated with software development, but their potential applications are much broader. For non-programmers, they can become powerful tools for solving diverse data management and project coordination tasks.

One prominent example is using Gitea for synchronizing notes. For instance, users of note-taking applications like Obsidian can use Gitea to version their notes. This allows tracking changes, reverting to previous versions, and even collaborating on notes with other users.

Another common scenario is using Gitea as a tool for synchronizing and versioning passwords with a password manager like Pass. This approach increases password management security by providing change history, synchronization between devices, and the ability to restore previous states.

System administrators and Linux enthusiasts will also find Gitea particularly useful. For them, the system can serve as a reliable repository for system and application configuration files. In case of need, it's easy to track changes made to configuration files and, if necessary, revert to an earlier version. This is especially important when changes to the configuration can affect system stability.

Additionally, Gitea can serve to manage content and project documentation. For example, organizations can use built-in wikis to create and store technical manuals, instructions, and other documents, which is especially useful in conditions of frequent changes and the need to provide access to current information.

Gitea is supported by an active community of developers and users who regularly update and supplement the documentation, making the system accessible to both beginners and professionals. Users can seek help through GitHub, specialized forums, and chats where they can ask questions, share experiences, or find solutions to specific problems. This ensures reliable support and constant platform development.

Alternatives and When to Choose Gitea

Choosing the right version control system depends on the specific needs of the project or organization. Gitea stands out among similar systems due to its lightness and minimal resource requirements, making it ideal for small teams or individual developers who need a simple and effective tool without complex infrastructure.

Unlike GitHub, which is a popular commercial platform, Gitea provides full control over your data since it can be deployed in your own infrastructure. This can be critically important for organizations requiring strict adherence to privacy and security policies.

GitLab, while offering extensive CI/CD capabilities, requires significantly more resources for its operation and has a complex structure, which may be excessive for small projects. Moreover, not all GitLab features are available in the free version, which can also influence the choice in favor of more accessible solutions.

Thus, if your goal is to ensure ease of management, minimize infrastructure costs, and maintain full control over the system and data, Gitea is an excellent choice.

Installation Process

Before installing Gitea itself, we will perform a series of preparatory steps.

We will use a cloud server and install Gitea on Ubuntu 22.04, but it should be noted that the Gitea installation process in other Linux distributions is not significantly different.

Creating a Cloud Server

Go to the Hostman control panel and click Create server in the Cloud Servers section. Choose Ubuntu 22.04 as the operating system. Select the region and the minimum available server configuration. Leave the default settings for the network: create a public IP and no private network.

For increased reliability, consider enabling the backup service. This service can be important if additional data redundancy is needed. We will look at the process of creating backups manually, but a full server backup can be useful for ensuring redundancy.

Specify the SSH key, set the server name, and complete the order by clicking the Order button.

After creating the server, connect to it via SSH and update the system with the following commands:

apt update
apt upgrade

These commands will update the system to the latest available package versions.

Setting Up the Database

Before starting the installation, it is necessary to prepare the database that will be used to store all information related to the version control system. We will use MariaDB, a popular database management system known for its performance and compatibility with MySQL.

Installing MariaDB

First, install MariaDB on your server with the command:

apt install mariadb-server

This command will install MariaDB along with all necessary dependencies.

Securing MariaDB

After installation, run the mysql_secure_installation script, which will help to configure security settings:

set a password for the root user,
remove anonymous users,
restrict remote database access,
remove the test database.

This will improve the security of your database server:

mysql_secure_installation

Follow the on-screen prompts to complete the setup.

Creating a User and Database

Next, log in to the MariaDB console and create a user and database that will be used by the system:

mysql -u root -p

After logging in, execute the following commands:

CREATE USER 'hostmangitea'@'%' IDENTIFIED BY 'secretpass';

This command creates a new database user. Here 'hostmangitea'@'%' specifies the username and the host from which they can connect. The % symbol means that the user can connect from any host. The part IDENTIFIED BY 'secretpass' sets the password for this user. It is important to choose a reliable and secure password.

CREATE DATABASE giteadb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_unicode_ci';

This command creates a new database named giteadb. It also specifies that the database will use UTF-8 for storing characters, which is suitable for texts in any language.

GRANT ALL PRIVILEGES ON giteadb.* TO 'hostmangitea';

This command grants the hostmangitea user all rights to work with the giteadb database. This includes read, write, and modify data rights, which are necessary for the full operation of the application.

FLUSH PRIVILEGES;

This command applies all privilege changes made. It updates the privileges so that the new settings take effect immediately without restarting the server. To exit mysql, press CTRL+D.

Installing Gitea

To install Gitea on your server, follow these steps.

Download and Install the Executable File

Download the latest stable version of Gitea from the official website:

wget -O gitea https://dl.gitea.io/gitea/1.22.0/gitea-1.22.0-linux-amd64

You can see the list of all available versions on the Gitea website.

Make the downloaded file executable:

chmod +x gitea

Check the Installed Version of Git

Make sure Git is installed on your server, as it is necessary for Gitea to work:

git --version

Create a System User

Create a separate user under which Gitea will run:

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

Set Up Directory Structure

Create the necessary directories for storing data, configurations, and logs:

mkdir -p /var/lib/gitea/{custom,data,log}
chown -R git:git /var/lib/gitea/
chmod -R 750 /var/lib/gitea/
mkdir /etc/gitea
chown root:git /etc/gitea
chmod 770 /etc/gitea

Set the Working Directory and Copying the File

Set the environment variable for the working directory and copy the executable file to the system directory:

export GITEA_WORK_DIR=/var/lib/gitea/
cp gitea /usr/local/bin/gitea

Creating and Configuring the Service for systemd

Create a service file for systemd so that Gitea starts automatically on system startup:

nano /etc/systemd/system/gitea.service

Insert the following configuration file in the editor window:

[Unit]
Description=MyGitea
After=network.target
Wants=mariadb.service
After=mariadb.service

[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

Then enable and start the service:

systemctl enable gitea
systemctl start gitea

Check that the service is running:

systemctl status gitea

Completing the Installation via the Web Interface

Now you can go to the IP address of your server and open the setup page in a browser: http://<your_server_ip>:3000. You will be greeted by the installation wizard. At this stage, you will need to configure the database connection and create an administrator account.

Database Configuration

In the Database Type field, select MySQL, corresponding to your database type.
In the Host field, leave the default value.
Enter the database username in the Username field — in your case, it is hostmangitea.
Enter the password you set when creating the database user in the Password field.
In the Database Name field, specify the name of your database, which you set earlier, giteadb.

General Settings

In the General Settings section, you can leave the default values. These settings include path and base URL configurations, which can be changed later if necessary.

Creating an Administrator Account

In the Administrator Account Settings section, you need to create an administrator account by specifying the desired username, password, and contact email. This account will be used to log in to the system and manage Gitea.

Completing the Installation

After filling in all the necessary information, click the Install Gitea button. The installation process will begin, and after completion, you will be able to log into the system using the created administrator account.

Setting Up Nginx and SSL for Your Domain

After installation, to ensure security and proper operation on your own domain, it is recommended to configure the Nginx web server and install an SSL certificate. This will protect the data and ensure encryption during transmission over the internet.

Installing and Configuring Nginx

Install Nginx on your server:

sudo apt install nginx

Create a configuration file for your domain in Nginx:

nano /etc/nginx/sites-available/hostmangitea.test.ru

Insert the following configuration, replacing hostmangitea.test.ru with your domain:

server {
    listen 80;
    server_name hostmangitea.test.ru;

    location / {
        client_max_body_size 512M;
        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;
        add_header Strict-Transport-Security "max-age=15552000; includeSubDomains" always;
    }
}

Activate the new configuration by creating a symbolic link in the sites-enabled directory:

sudo ln -s /etc/nginx/sites-available/hostmangitea.test.ru /etc/nginx/sites-enabled/

Installing an SSL Certificate with Certbot

Install Certbot and its Nginx plugin:

sudo apt install certbot python3-certbot-nginx

Run Certbot to automatically install the SSL certificate for your domain:

certbot --non-interactive -m [email protected] --agree-tos --no-eff-email --nginx -d hostmangitea.test.ru

This command will issue and configure the SSL certificate, automatically updating the Nginx configuration to use HTTPS. In the command, change [email protected] to your email and hostmangitea.test.ru to your domain.

Restart Nginx to apply the changes:

sudo systemctl restart nginx

Now, the service is available over a secure HTTPS connection on your domain.

Additionally, you can edit the /etc/gitea/app.ini configuration file to set up the domain and access level. In the [server] section of the configuration file, change the values of SSH_DOMAIN, DOMAIN, and ROOT_URL to your domain instead of the IP address. This will correctly display links in your version control system.

In the [service] section of the /etc/gitea/app.ini file, you can set the DISABLE_REGISTRATION parameter to true to disable new user registrations. This will increase the security of your system by restricting access to selected users only.

To apply the changes, restart the service with the command:

sudo systemctl restart gitea

Security and Backup

To ensure the security of your data, configure a firewall on the server and set up a backup system.

Configuring the UFW Firewall

Properly configuring the firewall is important for securing your server. Using ufw (Uncomplicated Firewall), you can easily manage access to various ports and services. Below are the basic steps for configuring ufw:

Reset the current firewall settings:

sudo ufw reset

Deny incoming connections by default and allow outgoing:

sudo ufw default deny incoming
sudo ufw default allow outgoing

Allow access to standard web ports and SSH:

sudo ufw allow 80
sudo ufw allow 443
sudo ufw allow 22

Deny access to your git server on ip:3000 for external connections:

sudo ufw allow from 127.0.0.1 to any port 3000
sudo ufw deny 3000

Activate and check the status of the firewall:

sudo ufw enable
sudo ufw status

Creating a Backup

Regular backups are a key aspect of maintaining data security. For Gitea, the backup process can be done as follows:

Switch to the user under which Gitea runs:

su git

Go to the directory where the backup will be created (e.g., /home/git):

cd /home/git

Run the command to create a data dump:

/usr/local/bin/gitea dump -c /etc/gitea/app.ini

This command will create an archive with the backup, including the database, configuration files, repositories, and other important data.

The created archive will contain important components such as:

app.ini — configuration file (if it was outside the standard custom/ folder),
custom/ — all custom settings if used,
data/ — application data including attachments and avatars,
repos/ — full copy of the repository directory,
gitea-db.sql — database dump,
log/ — various logs, although they are not essential for recovery.

Restoring from a Backup

To restore data from a backup, follow these steps:

Unzip the backup archive:

unzip gitea-dump-id.zip

Go to the directory with the extracted data:

cd gitea-dump-id

Now restore the main components. Configuration files:

mv app.ini /etc/gitea/conf/app.ini

Application data:

mv data/* /var/lib/gitea/data/

Logs:

mv log/* /var/lib/gitea/log/

Repositories:

mv repos/* /var/lib/gitea/gitea-repositories/

Update permissions:

chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea

Import the database dump into MySQL:

mysql --default-character-set=utf8mb4 -u$USER -p$PASS $DATABASE < gitea-db.sql

Replace $USER, $PASS, and $DATABASE with the username, password, and database name respectively.

These steps will allow you to restore all necessary information and data on your server after a failure or transfer to a new server.

Conclusion

In this article, we thoroughly reviewed the process of installing Gitea on your server as well as configuring it, starting from the basic installation, going through security and backup configuration, and ending with integration with external services for application deployment. Now you have the knowledge on how to effectively use version control systems to manage your code versions and automate development. The platform provides a reliable and scalable foundation, allowing you to significantly increase development productivity and enhance control over project changes.

Git