Back to Blog

Forgejo Installation Guide (MariaDB)

Overview

This guide describes how to install Forgejo on a RHEL-based system (Rocky Linux, AlmaLinux, CentOS, Fedora) using:

  • MariaDB as the database
  • Native Forgejo binary
  • systemd service
  • Dedicated git system user

Prerequisites

  • Root or sudo access
  • Internet connectivity
  • Clean system recommended

1. System Preparation

The first step is to update the operating system packages and install the necessary dependencies, including git and git-lfs, which are essential for Forgejo to function.

sudo dnf update -y
sudo dnf install -y wget tar curl nano git git-lfs

2. Install and Secure MariaDB

2.1 Install MariaDB Server

Forgejo requires a relational database to manage users, repositories, and metadata. MariaDB is the standard choice for performance and compatibility on RHEL systems.

sudo dnf install -y mariadb-server
sudo systemctl enable --now mariadb

2.2 Secure MariaDB

Run this security script to remove unsafe default settings, set the database root password, and disable unprotected remote access.

sudo mysql_secure_installation

3. Create Forgejo Database and User

We need to prepare a dedicated space within MariaDB where Forgejo can write its data in an isolated and secure manner.

# Log into the MariaDB console
sudo mysql -u root -p
-- Ensure compatibility with modern authentication plugins
SET old_passwords=0;

-- Create the dedicated user (replace 'passw0rd' with a strong password)
CREATE USER 'forgejo'@'%' IDENTIFIED BY 'passw0rd';

-- Create the database with binary collation for correct Git metadata support
CREATE DATABASE forgejodb
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_bin;

-- Grant privileges to the user on the newly created database
GRANT ALL PRIVILEGES ON forgejodb.* TO 'forgejo';

FLUSH PRIVILEGES;
EXIT;

4. Download and Install Forgejo

Forgejo is distributed as a single binary file. We will download it, make it executable, and move it to the standard system path for local binaries.

# Download the specific version (v13.0.3) from Codeberg
wget https://codeberg.org/forgejo/forgejo/releases/download/v13.0.3/forgejo-13.0.3-linux-amd64

# Make the file executable
chmod +x forgejo-13.0.3-linux-amd64

# Copy the binary to the system path and set correct permissions
sudo cp forgejo-13.0.3-linux-amd64 /usr/local/bin/forgejo
sudo chmod 755 /usr/local/bin/forgejo

5. Create Forgejo User

For security best practices, Forgejo should never run as root. We create a dedicated system user named git to handle all repository operations.

sudo useradd --system --shell /bin/bash \
  --comment 'Git Version Control' \
  --create-home --home-dir /home/git \
  --user-group git

6. Create Required Directories

Forgejo needs specific folders to store application data (repositories, avatars, LFS files) and configuration files.

# Directory for application data
sudo mkdir /var/lib/forgejo
sudo chown git:git /var/lib/forgejo
sudo chmod 750 /var/lib/forgejo

# Directory for configuration
sudo mkdir /etc/forgejo
sudo chown root:git /etc/forgejo
sudo chmod 770 /etc/forgejo

7. Configure systemd Service

We download the official service template and modify it to depend on MariaDB.

# Download official template
sudo wget https://codeberg.org/forgejo/forgejo/src/branch/forgejo/contrib/systemd/forgejo.service -P /etc/systemd/system/

# Update the service file to use MariaDB
sudo sed -i 's/After=network.target/After=network.target mariadb.service/' /etc/systemd/system/forgejo.service
sudo sed -i '/After=network.target mariadb.service/a Wants=mariadb.service' /etc/systemd/system/forgejo.service

Uncomment MariaDB dependencies:

Wants=mariadb.service
After=network.target mariadb.service

8. Start Forgejo

Reload the systemd daemon and start the service.

sudo systemctl daemon-reload
sudo systemctl enable --now forgejo.service

# Check status
sudo systemctl status forgejo.service

9. Access Forgejo

Find your server IP and open the setup wizard in your browser.

ip a

URL: http://server-ip:3000

10. First-Time Setup

Use these values in the web installer:

  • Database Type: MariaDB
  • Database Name: forgejodb
  • Database User: forgejo
  • Database Password: passw0rd
  • Data Path: /var/lib/forgejo

Forgejo is now ready.

Back to all posts