Skip to content

Gitea Installation & Configuration Guide

Installation Instructions

Step 1: Download Gitea Binary

Download the latest Gitea release for Linux (amd64 architecture) from the GitHub releases page: 

VERSION="1.21.0"  # Replace with desired version
wget https://github.com/go-gitea/gitea/releases/download/v${VERSION}/gitea-${VERSION}-linux-amd64 -O gitea

Step 2: Make Binary Executable

Grant execute permissions to the downloaded Gitea binary: 

chmod +x gitea

Step 3: Move to System Path

Move the executable to the system binary directory so it can be run from anywhere: 

sudo mv gitea /usr/local/bin/gitea

Step 4: Create System User

Create a dedicated user for Gitea to run under (for security): 

sudo useradd -r -m -d /var/lib/gitea gitea

Step 5: Create Required Directories

Set up the directory structure and set proper permissions: 

sudo mkdir -p /var/lib/gitea/{data,log,sessions,tmp}
sudo mkdir -p /etc/gitea
sudo chown -R gitea:gitea /var/lib/gitea /etc/gitea
sudo chmod 750 /etc/gitea  # Restrict config directory access

Step 6: Configure Gitea

Place the configuration file at /etc/gitea/app.ini (see configuration section below).

Step 7: Install Systemd Service

Create the systemd unit file at /etc/systemd/system/gitea.service (see systemd section below).

Step 8: Enable and Start Service

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

Step 9: Verify Installation

Check service status and logs: 

sudo systemctl status gitea
sudo journalctl -u gitea -n 50  # View last 50 lines

Step 10: Restart Service (After Updates)

When updating Gitea, download the new binary, move it to /usr/local/bin/gitea, then restart: 

sudo systemctl restart gitea

Systemd Service Configuration

The systemd service file should be placed at /etc/systemd/system/gitea.service:

[Unit]
Description=Gitea
After=network.target mariadb.service

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

[Install]
WantedBy=multi-user.target

Service Configuration Breakdown

Setting Purpose
[Unit] Metadata about the service
Description Human-readable name for the service
After Services that must start before Gitea; waits for network and MariaDB
[Service] Service execution parameters
Type=simple Service runs in foreground (Gitea process remains active)
User=gitea System user that runs the Gitea process (for security)
Group=gitea System group for the Gitea process
WorkingDirectory Base directory for Gitea operations and data storage
ExecStart Command to start Gitea (runs the web interface with config file)
Restart=always Automatically restart service if it crashes
Environment Set environment variables for the process
[Install] Boot-time installation settings
WantedBy=multi-user.target Service starts in multi-user mode (standard server environment)

Application Configuration (app.ini)

Place this configuration file at /etc/gitea/app.ini. Customize values as needed for your environment.

# Application Settings
APP_NAME = Chris Private Git
RUN_MODE = prod
RUN_USER = gitea
WORK_PATH = /var/lib/gitea

# Repository Storage
[repository]
ROOT = /var/lib/gitea/data/repos

[repository.local]
LOCAL_COPY_PATH = /var/lib/gitea/tmp/local-repo

[repository.upload]
TEMP_PATH = /var/lib/gitea/uploads

# Server Configuration
[server]
APP_DATA_PATH = /var/lib/gitea
DOMAIN = git.skynet.lan
SSH_DOMAIN = git.skynet.lan
HTTP_PORT = 3001
ROOT_URL = http://git.skynet.lan/
DISABLE_SSH = true
SSH_PORT = 22
SSH_LISTEN_PORT = 22
LFS_START_SERVER = true
OFFLINE_MODE = false

# Database Configuration
[database]
DB_TYPE  = mysql
HOST     = 127.0.0.1:3306
NAME     = gitea
USER     = gitea
PASSWD   = gitea

# Search Indexer
[indexer]
ISSUE_INDEXER_PATH = /var/lib/gitea/indexers/issues.bleve

# Session Storage
[session]
PROVIDER_CONFIG = /var/lib/gitea/sessions
PROVIDER = file

# Avatar & Repository Images
[picture]
AVATAR_UPLOAD_PATH = /var/lib/gitea/avatars
REPOSITORY_AVATAR_UPLOAD_PATH = /var/lib/gitea/repo-avatars

# File Attachments
[attachment]
PATH = /var/lib/gitea/attachments

# Logging
[log]
MODE = console
LEVEL = info
ROOT_PATH = /var/lib/gitea/log

# Security Settings
[security]
INSTALL_LOCK = true
SECRET_KEY = 
REVERSE_PROXY_LIMIT = 1
REVERSE_PROXY_TRUSTED_PROXIES = *
PASSWORD_HASH_ALGO = pbkdf2

# Service Features
[service]
DISABLE_REGISTRATION = false
REQUIRE_SIGNIN_VIEW = false
REGISTER_EMAIL_CONFIRM = false
ENABLE_NOTIFY_MAIL = false
ALLOW_ONLY_EXTERNAL_REGISTRATION = false
ENABLE_CAPTCHA = false
DEFAULT_KEEP_EMAIL_PRIVATE = false
DEFAULT_ALLOW_CREATE_ORGANIZATION = true
DEFAULT_ENABLE_TIMETRACKING = true
NO_REPLY_ADDRESS = noreply.localhost

# Git LFS (Large File Storage)
[lfs]
PATH = /var/lib/gitea/data/lfs

# Email/Mailer
[mailer]
ENABLED = false

# OpenID Authentication
[openid]
ENABLE_OPENID_SIGNIN = true
ENABLE_OPENID_SIGNUP = true

# Update Checker
[cron.update_checker]
ENABLED = false

# Pull Request Settings
[repository.pull-request]
DEFAULT_MERGE_STYLE = merge

# Repository Signing
[repository.signing]
DEFAULT_TRUST_MODEL = committer

Configuration Reference

General Settings

  • APP_NAME: Display name for your Gitea instance
  • RUN_MODE: Set to prod for production, dev for development
  • RUN_USER: System user running Gitea (must match systemd User setting)
  • WORK_PATH: Base working directory for Gitea

Server Configuration

  • DOMAIN: Hostname for the Gitea instance (used for links)
  • HTTP_PORT: Internal port Gitea listens on (use with reverse proxy)
  • ROOT_URL: Public URL users access (should match your reverse proxy)
  • DISABLE_SSH: Set to true if using reverse proxy for web-only access
  • LFS_START_SERVER: Enable Git Large File Storage support

Database Configuration

  • DB_TYPE: Database backend (mysql, postgres, sqlite3)
  • HOST: Database server address and port
  • NAME: Database name
  • USER/PASSWD: Database credentials

Security Settings

  • INSTALL_LOCK: Set to true after initial setup to prevent re-installation
  • REVERSE_PROXY_TRUSTED_PROXIES: IP addresses of trusted reverse proxies
  • PASSWORD_HASH_ALGO: Algorithm for password hashing

Nginx Reverse Proxy Configuration

Place this configuration in your Nginx configuration directory (e.g., /etc/nginx/conf.d/gitea.conf):

server {
    listen 80;
    server_name git.skynet.lan;

    location / {
        proxy_pass http://127.0.0.1:3001/;
        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;
    }
}

Enabling the Configuration

  1. Test Nginx configuration: 

    sudo nginx -t

  2. Reload Nginx: 

    sudo systemctl reload nginx

Quick Reference Commands

# Start/stop/restart Gitea
sudo systemctl start gitea
sudo systemctl stop gitea
sudo systemctl restart gitea

# Check service status
sudo systemctl status gitea

# View service logs
sudo journalctl -u gitea -f  # Follow logs in real-time
sudo journalctl -u gitea -n 100  # View last 100 lines

# Reload systemd daemon (after editing service file)
sudo systemctl daemon-reload

# Enable/disable service on boot
sudo systemctl enable gitea
sudo systemctl disable gitea