Step‑by‑Step Guide: Install and Configure Gitea on Ubuntu 18.04

Introduction

Gitea is a lightweight, self‑hosted Git server written in Go. It provides repository browsing, issue tracking, wiki, and user management, and can be used as a low‑resource alternative to GitLab.

Prerequisites

Database : SQLite (default), PostgreSQL or MySQL/MariaDB are also supported.

Git : required to run Gitea.

Install SQLite and Git on Ubuntu (or any Debian‑based distro):

sudo apt update
sudo apt install sqlite3 git

Create a dedicated system user

Run Gitea under a non‑login system account named git:

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

Download and install the Gitea binary

Set the desired version (replace 1.10.2 with the latest release) and download the binary:

VERSION=1.10.2
sudo wget -O /tmp/gitea \
    https://dl.gitea.io/gitea/${VERSION}/gitea-${VERSION}-linux-amd64

Move it to a directory in $PATH and make it executable:

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

Create required directories and set permissions

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

Systemd service unit

Download the pre‑configured unit file, reload systemd and enable the service:

sudo wget https://raw.githubusercontent.com/go-gitea/gitea/master/contrib/systemd/gitea.service \
    -P /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now gitea

Web installer configuration

Open a browser and navigate to http://your-domain-or-IP:3000. Use the following settings (adjust paths if needed):

Database type : SQLite3

Path : /var/lib/gitea/data/gitea.db Site name : your organization name

Repository root path : /home/git/gitea-repositories Git LFS root path : /var/lib/gitea/data/lfs Run as user : git SSH server domain : your-domain-or-IP SSH port : 22 Gitea HTTP listen port : 3000 Gitea base URL : http://your-domain-or-IP:3000/ Complete the installation, create the first admin user, and log in.

Optional: Nginx as SSL/TLS termination proxy

To expose Gitea over HTTPS, configure Nginx as a reverse proxy and obtain a Let’s Encrypt certificate for your domain (e.g., git.example.com).

server {
    listen 80;
    server_name git.example.com;
    include snippets/letsencrypt.conf;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name git.example.com;

    proxy_read_timeout 720s;
    proxy_connect_timeout 720s;
    proxy_send_timeout 720s;
    client_max_body_size 50m;

    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;

    ssl_certificate /etc/letsencrypt/live/git.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/git.example.com/privkey.pem;
    include snippets/ssl.conf;

    location / {
        proxy_redirect off;
        proxy_pass http://127.0.0.1:3000;
    }
}

After editing the file, restart Nginx and update Gitea’s app.ini:

sudo systemctl restart nginx

# /etc/gitea/app.ini
[server]
DOMAIN = git.example.com
ROOT_URL = https://git.example.com/

Restart Gitea to apply the changes:

sudo systemctl restart gitea

Email notification configuration

Install an MTA (e.g., Postfix) or use an external SMTP service, then edit /etc/gitea/app.ini:

[mailer]
ENABLED = true
HOST = SMTP_SERVER:SMTP_PORT
FROM = SENDER_EMAIL
USER = SMTP_USER
PASSWD = YOUR_SMTP_PASSWORD

Restart Gitea after saving:

sudo systemctl restart gitea

Upgrading Gitea

To upgrade to a newer version, stop the service, download the new binary, replace the old one, set executable permission, and start the service:

sudo systemctl stop gitea
VERSION=1.20.0   # replace with the latest version
sudo wget -O /tmp/gitea \
    https://dl.gitea.io/gitea/${VERSION}/gitea-${VERSION}-linux-amd64
sudo mv /tmp/gitea /usr/local/bin/gitea
sudo chmod +x /usr/local/bin/gitea
sudo systemctl start gitea

Summary

This guide covers installing Gitea on Ubuntu (or any Debian‑based system), creating the required system user and directories, configuring a systemd service, performing the initial web‑based setup, optional HTTPS reverse‑proxy with Nginx, email notification setup, and the procedure for upgrading to newer releases.