How to Install Gitea Code Hosting Platform with HTTPS on CentOS 8

Gitea is a code hosting web application written in Go. As its name suggests, it is designed to be used with the popular source control program Git, similarly to Gitlab and Github. This guide will explain the installation of Gitea on CentOS 8 with an Nginx HTTPS reverse proxy.

Requirements

• A CentOS 8 system on which you have root privileges.
• A registered domain name pointing to your server.
• The $EDITOR environment variable should be set to your preferred text editor.
• Access to an SMTP server for email notifications (optional).

Make sure your (sub)domain points to the IPv4 address of your server with an A record. Optionally, create an AAAA record pointing to your server’s IPv6 address.

NOTE: This guide assumes SELinux is set to either disabled or permissive. 

Step 1: Preparing the system

Start by installing any available updates and rebooting:
dnf update -y
reboot


For this setup, several software components are required:

• Git, a dependency of Gitea.
• PostgreSQL, as Gitea requires a database.
• Nginx, which will be used as a reverse proxy.
• Sudo, to run commands as the postgres system user.
• Wget
• Certbot, a utility for obtaining Let’s Encrypt SSL certificates. Certbot will be installed separately as it is not available in the CentOS software repositories.

Install them as follows:
dnf install -y git postgresql postgresql-server nginx sudo wget


Certbot-auto is a script that manages certbot’s installation. Download it:
wget https://dl.eff.org/certbot-auto -O /usr/local/bin/certbot-auto


Ensure the correct permissions are set:
chmod 0755 /usr/local/bin/certbot-auto


Run the following to install certbot. You will be prompted by the package manager to confirm the installation of dependencies, answer ‘y’.
certbot-auto --install-only


Next, create a user to run Gitea:
useradd --system --shell /bin/bash --create-home --home-dir /home/gitea gitea


Then create the directory structure for Gitea:
mkdir -p /var/lib/gitea/{data,log} /etc/gitea /run/gitea


And set ownerships and permissions as follows:
chown -R gitea:gitea /var/lib/gitea
chown -R gitea:gitea /var/run/gitea
chown -R root:gitea /etc/gitea
chmod -R 750 /var/lib/gitea
chmod 770 /etc/gitea


The permissions on /etc/gitea are temporary and will be tightened after running the web installer.

Enable traffic to ports 80 and 443 permanently:
firewall-cmd --add-port 80/tcp --add-port 443/tcp --permanent
firewall-cmd --reload


Access to port 3000 is only temporarily required for the initial setup as we will configure gitea to use a Unix socket instead.
firewall-cmd --add-port 3000/tcp

Step 2: Database Setup

Initialize Postgres:
postgresql-setup --initdb --unit postgresql


Make sure it is enabled and running:
systemctl enable --now postgresql.service


Log into Postgres:
sudo -u postgres psql


Then create a user role and database to be used by Gitea:
postgres=# CREATE ROLE gitea LOGIN ENCRYPTED PASSWORD 'your_password';
postgres=# CREATE DATABASE gitea;
postgres=# GRANT ALL PRIVILEGES ON DATABASE gitea TO gitea;
postgres=# q


Open the Postgres client authentication configuration file:
$EDITOR /var/lib/pgsql/data/pg_hba.conf


Add the following line right after # IPv4 local connections :
# IPv4 local connections:
host gitea gitea 127.0.0.1/32 md5


Save the file and restart Postgres:
systemctl restart postgresql.service

Step 3: Installing Gitea

Download the linux-amd64 binary version of Gitea from Gitea’s download page. For example:
wget https://dl.gitea.io/gitea/master/gitea-master-linux-amd64 -O /usr/local/bin/gitea


Set the correct permissions on the downloaded binary:
chmod 755 /usr/local/bin/gitea


Next, create a systemd unit file:
$EDITOR /etc/systemd/system/gitea.service


And enter the following:
[Unit] Description=Gitea (Git with a cup of tea)
After=syslog.target
After=network.target
Requires=postgresql.service
[Service] Type=simple
User=gitea
Group=gitea
WorkingDirectory=/var/lib/gitea/
RuntimeDirectory=gitea
ExecStart=/usr/local/bin/gitea web -c /etc/gitea/app.ini
Restart=always
Environment=USER=gitea HOME=/home/gitea GITEA_WORK_DIR=/var/lib/gitea
[Install] WantedBy=multi-user.target


Make sure the new unit is loaded:
systemctl daemon-reload


Then instruct systemd to start Gitea at boot:
systemctl enable gitea.service

Step 4: Configuring Gitea

For the initial configuration, we’ll use the included web installer. First, start Gitea:
systemctl start gitea.service


Then navigate to http://your_domain:3000/install and fill in the required parameters as follows:

• Database Type: PostgreSQL
• Host: 127.0.0.1:5432
• Username: gitea
• Password: Enter the password you chose during Postgres role creation.
• Database Name: gitea
• SSL: Disable
• Site Title: Title of your choice.
• Repository Root Path: /var/lib/gitea/data/repositories
• Git LFS Root Path: /var/lib/gitea/data/lfs
• Run As Username: gitea
• SSH Server Domain: your_domain
• SSH Server Port: 22
• Gitea HTTP Listen Post: 3000
• Gitea Base URL: https://your_domain/
• Log Path: /var/lib/gitea/log

Configure email and the remaining settings as deemed fit, then click “Install Gitea”. You will be redirected to a faulty URL. This is normal, as we haven’t configured Nginx or HTTPS yet. For performance reasons, we will now configure Gitea to listen on a unix socket instead of the default TCP port.

Stop Gitea before proceeding:
systemctl stop gitea.service


Tighten permissions on /etc/gitea as shown below. This prevents anyone not in the gitea group from reading app.ini , which contains sensitive information, including database credentials.
chmod 750 /etc/gitea
chown root:gitea /etc/gitea/app.ini
chmod 640 /etc/gitea/app.ini


Open its configuration file:
$EDITOR /etc/gitea/app.ini


Remove the following line from the server section:
HTTP_PORT = 3000


And add the following lines in the server section:
HTTP_ADDR = /run/gitea/gitea.sock
PROTOCOL = unix
UNIX_SOCKET_PERMISSION = 666

Step 5: Reverse Proxy Setup

Stop Nginx if it is running, to allow certbot to listen on port 80:
systemctl stop nginx.service


Use the following command to obtain a certificate for your domain:
certbot-auto certonly --standalone --agree-tos -m [email protected] -d your_domain


Let’s Encrypt will verify domain ownership before issuing the certificate. Your certificate, chain, and private key will be stored in /etc/letsencrypt/live/your_domain/ .

We can now configure Nginx. Create a new configuration file:
$EDITOR /etc/nginx/conf.d/gitea.conf


And enter the following server blocks:
server {
listen 80;
listen [::]:80;
server_name your_domain;
return 301 https://$server_name$request_uri;
access_log /var/log/nginx/gitea-proxy_access.log;
error_log /var/log/nginx/gitea-proxy_error.log;
}
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name your_domain;
ssl on;
ssl_certificate /etc/letsencrypt/live/your_domain/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your_domain/privkey.pem;
location / {
proxy_pass http://unix:/var/run/gitea/gitea.sock;
}
access_log /var/log/nginx/gitea-proxy_access.log;
error_log /var/log/nginx/gitea-proxy_error.log;
}

The first server block simply serves to redirect all HTTP requests to HTTPS. The second block listens for HTTPS connections and proxies them to the Unix socket on which we have configured Gitea to listen.

Once you’ve saved the above configuration, check for any syntax errors and edit your configuration if necessary:
nginx -t


Finally, start Nginx and Gitea:
systemctl start nginx.service gitea.service


Your Gitea instance should now be running successfully. Access it at https://your_domain

Optional Steps

Logging Configuration

By default, Gitea’s logs messages of severity level Info and above. You will most likely want to change that to Warn or Error . To do so, open /etc/gitea/app.ini and change the LEVEL parameter in the [log] section to one of: trace, debug, info, warn, error, critical, fatal, none. For example, to log messages of severity Warn and above, use:
[log] MODE = file
LEVEL = warn
ROOT_PATH = /var/lib/gitea/log


Restart Gitea for the changes to take effect:
systemctl restart gitea.service


Separate SSH server

Gitea can alternatively use its own SSH server. To enable it, add the following line to the [server] configuration section:
START_SSH_SERVER = true


And change the SSH port to any number above 1024, for example:
SSH_PORT = 2222


Then restart Gitea to apply the changes and enable traffic to the chosen port:
firewall-cmd --add-port 2222/tcp --permanent
firewall-cmd --reload