Installation

Choose Your Installation Method

Gitea offers multiple installation methods to suit your needs. Choose the one that works best for your environment.

Docker

Recommended - Fastest way to get started with full isolation

Binary

Single executable file - no dependencies required

Package Manager

Install via your system’s package manager

From Source

Build from source for development or customization

Docker Installation

Docker is the recommended installation method for most users. It provides isolation, easy updates, and consistent behavior across platforms.

Using Docker

The simplest way to run Gitea is with Docker:

Create directories for persistent data

mkdir -p /var/lib/gitea

Run Gitea container

docker run -d \
  --name=gitea \
  -p 3000:3000 \
  -p 222:22 \
  -v /var/lib/gitea:/data \
  -e USER_UID=1000 \
  -e USER_GID=1000 \
  gitea/gitea:latest

Port 3000: Web interface (HTTP)
Port 222: SSH access (mapped to container’s port 22)
Volume /data: Persistent storage for repositories and database

Access Gitea

Open your browser and navigate to http://localhost:3000You’ll see the initial configuration page where you can set up your instance.

Using Docker Compose

For production deployments, use Docker Compose with a PostgreSQL database:

version: "3"

networks:
  gitea:
    external: false

services:
  server:
    image: gitea/gitea:latest
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=gitea
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
    depends_on:
      - db

  db:
    image: postgres:14
    restart: always
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=gitea
      - POSTGRES_DB=gitea
    networks:
      - gitea
    volumes:
      - ./postgres:/var/lib/postgresql/data

Make sure to change the default passwords in production!

Docker Rootless

For enhanced security, run Gitea as a non-root user:

docker run -d \
  --name=gitea \
  -p 3000:3000 \
  -p 222:2222 \
  -v /var/lib/gitea:/var/lib/gitea \
  -e USER_UID=1000 \
  -e USER_GID=1000 \
  gitea/gitea:latest-rootless

Binary Installation

Install Gitea as a standalone binary - perfect for environments without Docker.

Download the binary

Download the latest release for your platform from dl.gitea.com:

Linux (amd64)
Linux (arm64)
macOS
Windows

wget -O gitea https://dl.gitea.com/gitea/1.22/gitea-1.22-linux-amd64
chmod +x gitea

wget -O gitea https://dl.gitea.com/gitea/1.22/gitea-1.22-linux-arm64
chmod +x gitea

wget -O gitea https://dl.gitea.com/gitea/1.22/gitea-1.22-darwin-amd64
chmod +x gitea

Download gitea-1.22-windows-amd64.exe from dl.gitea.com

Verify the binary (optional but recommended)

# Download the checksum
wget https://dl.gitea.com/gitea/1.22/gitea-1.22-linux-amd64.sha256

# Verify
sha256sum -c gitea-1.22-linux-amd64.sha256

Run Gitea

./gitea web

Gitea will start on port 3000. Open http://localhost:3000 to complete the setup.

Setting up as a Service

For production use, run Gitea as a system service:

systemd (Linux)
Windows Service

Create a git user

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

Create required directories

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

sudo mkdir /etc/gitea
sudo chown root:git /etc/gitea
sudo chmod 770 /etc/gitea

Copy binary to system location

sudo cp gitea /usr/local/bin/gitea
sudo chmod +x /usr/local/bin/gitea

Create systemd service file

Create /etc/systemd/system/gitea.service with the following content:

[Unit]
Description=Gitea (Git with a cup of tea)
After=network.target

[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

Enable and start the service

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

# Check status
sudo systemctl status gitea

Use NSSM (Non-Sucking Service Manager) to run Gitea as a Windows service:

# Download NSSM from https://nssm.cc/download

# Install Gitea as a service
nssm install Gitea "C:\gitea\gitea.exe" web

# Start the service
nssm start Gitea

Package Manager Installation

Homebrew (macOS/Linux)
Snap (Linux)
Arch Linux (AUR)
Debian/Ubuntu

brew install gitea

# Start Gitea
gitea web

snap install gitea

yay -S gitea
# or
paru -S gitea

# Start and enable service
sudo systemctl enable --now gitea

Building from Source

For developers or custom builds with specific features:

Prerequisites

Go 1.26 or higher - Check with go version
Node.js LTS (for frontend) - Check with node --version
pnpm - Install with npm install -g pnpm
Git - Check with git --version
Build tools - gcc/build-essential

Clone the repository

git clone https://github.com/go-gitea/gitea.git
cd gitea

Build Gitea

Standard Build
With SQLite Support
Backend Only

TAGS="bindata" make build

TAGS="bindata sqlite sqlite_unlock_notify" make build

TAGS="bindata" make backend

Building takes a few minutes. The bindata tag embeds static assets into the binary.

Run Gitea

./gitea web

The binary will be created in the project root directory.

For more detailed build instructions, see the CONTRIBUTING.md file in the repository.

Database Setup

Gitea supports multiple database backends:

SQLite (Default)
PostgreSQL (Recommended)
MySQL/MariaDB

No setup required! Gitea uses SQLite by default.Perfect for:

Small installations (< 100 users)
Personal use
Testing and development

SQLite is embedded and requires no separate database server.

# Install PostgreSQL
sudo apt-get install postgresql

# Create database and user
sudo -u postgres psql

CREATE USER gitea WITH PASSWORD 'gitea';
CREATE DATABASE gitea OWNER gitea;
\q

During Gitea setup, enter:

Database Type: PostgreSQL
Host: localhost:5432
Username: gitea
Password: gitea
Database Name: gitea

# Install MySQL/MariaDB
sudo apt-get install mysql-server

# Create database and user
sudo mysql

CREATE DATABASE gitea CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_unicode_ci';
CREATE USER 'gitea'@'localhost' IDENTIFIED BY 'gitea';
GRANT ALL PRIVILEGES ON gitea.* TO 'gitea'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Initial Configuration

After starting Gitea for the first time:

Access the installer

Navigate to http://localhost:3000 in your browser

Configure database

Choose your database type and enter connection details

Configure server settings

Server Domain: Your domain or IP address
SSH Port: 22 (or custom port)
HTTP Port: 3000 (or custom port)
Base URL: Full URL to access Gitea

Create admin account

Set up the administrator account for your instance

Complete installation

Click “Install Gitea” to finalize the setup

After installation, the configuration is saved to custom/conf/app.ini. You can manually edit this file for advanced configuration.

Firewall Configuration

If you’re using a firewall, open the necessary ports:

# For UFW (Ubuntu/Debian)
sudo ufw allow 3000/tcp  # HTTP
sudo ufw allow 222/tcp   # SSH (if using custom port)

# For firewalld (CentOS/RHEL)
sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --permanent --add-port=222/tcp
sudo firewall-cmd --reload

Upgrading Gitea

Docker
Binary

# Stop the container
docker stop gitea

# Remove the old container
docker rm gitea

# Pull the latest image
docker pull gitea/gitea:latest

# Start with the same command you used initially
docker run -d ...

# Stop Gitea
sudo systemctl stop gitea

# Backup the old binary
sudo cp /usr/local/bin/gitea /usr/local/bin/gitea.backup

# Download and replace with new binary
sudo wget -O /usr/local/bin/gitea https://dl.gitea.com/gitea/1.22/gitea-1.22-linux-amd64
sudo chmod +x /usr/local/bin/gitea

# Start Gitea
sudo systemctl start gitea

Always backup your data before upgrading! Backup at minimum:

Database (if using external DB)
custom/conf/app.ini configuration file
Repository data directory

Troubleshooting

Gitea won't start

Check the logs:

Docker: docker logs gitea
Systemd: sudo journalctl -u gitea -n 50
Binary: Check log/gitea.log in your work directory

Common issues:

Port already in use
Permission issues with data directory
Database connection problems

Can't access via browser

Check if Gitea is running: sudo systemctl status gitea or docker ps
Verify firewall settings
Check that you’re using the correct IP/domain and port
Look for errors in logs

Database connection failed

Verify database is running
Check connection credentials in app.ini
Ensure database user has proper permissions
For PostgreSQL, check pg_hba.conf for connection rules

SSH not working

Ensure SSH port is open in firewall
Check SSH server is running
Verify SSH keys are properly configured
Check SSH_PORT in app.ini

Next Steps

Gitea is now installed! Continue with:

Quick Start Guide

Follow our 5-minute quick start to create your first repository

Configuration

Learn about advanced configuration options

Getting Started

Core Features

Administration

User Management

Integrations

Installation

Choose Your Installation Method

Docker

Binary

Package Manager

From Source

Docker Installation

Using Docker

Using Docker Compose

Docker Rootless

Binary Installation

Setting up as a Service

Package Manager Installation

Building from Source

Database Setup

Initial Configuration

Firewall Configuration

Upgrading Gitea

Troubleshooting

Next Steps

Quick Start Guide

Configuration

Build docs developers (and LLMs) love

Getting Started

Core Features

Administration

User Management

Integrations

​Choose Your Installation Method

Docker

Binary

Package Manager

From Source

​Docker Installation

​Using Docker

​Using Docker Compose

​Docker Rootless

​Binary Installation

​Setting up as a Service

​Package Manager Installation

​Building from Source

​Database Setup

​Initial Configuration

​Firewall Configuration

​Upgrading Gitea

​Troubleshooting

​Next Steps

Quick Start Guide

Configuration

Build docs developers (and LLMs) love

Choose Your Installation Method

Docker Installation

Using Docker

Using Docker Compose

Docker Rootless

Binary Installation

Setting up as a Service

Package Manager Installation

Building from Source

Database Setup

Initial Configuration

Firewall Configuration

Upgrading Gitea

Troubleshooting

Next Steps