Installation

Install Gitea on your platform with Docker, binaries, package managers, or from source

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:

1. Create directories for persistent data

   mkdir -p /var/lib/gitea
   
2. 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
3. Access Gitea

   Open your browser and navigate to http://localhost:3000

   You’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:

docker-compose.yml

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

docker-compose up -d

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.

1. Download the binary

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

   Linux (amd64)

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

   Linux (arm64)

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

   macOS

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

   Windows

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

2. 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
   
3. 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)

1. Create a git user

   sudo adduser \
     --system \
     --shell /bin/bash \
     --gecos 'Git Version Control' \
     --group \
     --disabled-password \
     --home /home/git \
     git
   
2. 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
   
3. Copy binary to system location

   sudo cp gitea /usr/local/bin/gitea
   sudo chmod +x /usr/local/bin/gitea
   
4. 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
   
5. Enable and start the service

   sudo systemctl daemon-reload
   sudo systemctl enable gitea
   sudo systemctl start gitea
   
   # Check status
   sudo systemctl status gitea
   

Windows Service

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)

brew install gitea

# Start Gitea
gitea web

Snap (Linux)

snap install gitea

Arch Linux (AUR)

yay -S gitea
# or
paru -S gitea

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

Debian/Ubuntu

Gitea is not in official Debian/Ubuntu repositories. Use Docker, binary, or build from source.

Building from Source

For developers or custom builds with specific features:

1. 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
2. Clone the repository

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

   Standard Build

   TAGS="bindata" make build
   

   With SQLite Support

   TAGS="bindata sqlite sqlite_unlock_notify" make build
   

   Backend Only

   TAGS="bindata" make backend
   

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

4. 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)

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.

PostgreSQL (Recommended)

# 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

MySQL/MariaDB

# 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:

1. Access the installer

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

2. Configure database

   Choose your database type and enter connection details

3. 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
4. Create admin account

   Set up the administrator account for your instance

5. 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

# 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 ...

Binary

# 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