Gitea Deployment & Usage Guide

1. Prerequisites

System Requirements

OS: Linux, macOS, Windows (x86, amd64, ARM, PowerPC)
Memory: Minimum 2GB RAM (4GB+ recommended)
Storage: Minimum 10GB free space (SSD recommended)
CPU: 2+ cores recommended

Required Software

Go: Version specified in go.mod (check current version in repository)
Node.js: LTS or greater (for frontend build)
pnpm: Latest version (npm install -g pnpm)
Git: 2.0+
Database (choose one):
- SQLite 3 (simplest for testing)
- MySQL 5.7+/MariaDB 10.4+/PostgreSQL 9.6+
- TiDB, MSSQL (experimental)
Reverse Proxy (optional but recommended):
- Nginx, Apache, Caddy, or Traefik

Optional Tools

Make: For build automation
Docker: For containerized deployment
Git LFS: For large file storage

2. Installation

From Binary (Recommended for Production)

Download the latest binary for your platform from Gitea Releases
Make executable:
```
chmod +x gitea
```
Place in system PATH (e.g., /usr/local/bin/gitea)

From Source (Development)

Clone repository:

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

Build backend:
```
make backend
```
Build frontend (if not using pre-built):
```
make frontend
```

Build complete binary:

TAGS="bindata" make build

For SQLite support:

TAGS="bindata sqlite sqlite_unlock_notify" make build

Using Docker

docker run -p 3000:3000 -p 2222:22 --name gitea \
  -v /path/to/data:/data \
  gitea/gitea:latest

3. Configuration

Initial Setup

On first run, Gitea will create:

app.ini configuration file
data/ directory for repositories and data

Configuration File (`app.ini`)

Location hierarchy (first found wins):

CUSTOM_CONFIG environment variable path
$GITEA_CUSTOM/conf/app.ini
$GITEA_WORK_DIR/conf/app.ini
conf/app.ini

Key sections:

[database]
DB_TYPE  = sqlite3  # or mysql, postgres, mssql, tidb
PATH     = %(APP_DATA_PATH)s/gitea.db
HOST     = localhost:3306
NAME     = gitea
USER     = gitea
PASSWD   = secure_password

[repository]
ROOT = /path/to/repositories

[server]
DOMAIN       = localhost
HTTP_PORT    = 3000
ROOT_URL     = http://localhost:3000/
DISABLE_SSH  = false
SSH_PORT     = 22
START_SSH_SERVER = false

Environment Variables

Override config with:

APP_DATA_PATH: Data directory (default: ~/.gitea)
GITEA_CUSTOM: Custom configuration directory
USER: Database user (if not set in config)
PASSWORD: Database password (if not set in config)

SSH Configuration

If using SSH:

Ensure SSH server is running on port 22 (or configured port)
Set START_SSH_SERVER = true in [server] to use Gitea's built-in SSH

Authorize Gitea user to access repositories:

sudo -u git ssh-keygen -t ed25519 -C "gitea@example.com"

4. Build & Run

Development Run

# From source directory
./gitea web

Access at http://localhost:3000

Production Run

Create dedicated user:

sudo useradd -r -s /bin/bash -m -d /var/lib/gitea gitea

Set up directories:

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

Copy binary and config:

sudo cp gitea /usr/local/bin/gitea
sudo cp conf/app.ini /var/lib/gitea/conf/app.ini

Edit /var/lib/gitea/conf/app.ini with production settings

Create systemd service (/etc/systemd/system/gitea.service):

[Unit]
Description=Gitea
After=network.target

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

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable gitea
sudo systemctl start gitea

5. Deployment

Recommended Platforms

Docker Compose (All-in-One)

version: "3"
services:
  gitea:
    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=secure_password
    volumes:
      - ./gitea:/data
      - ./custom:/etc/gitea
    ports:
      - "3000:3000"
      - "2222:22"
    depends_on:
      - db
  db:
    image: postgres:15
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=secure_password
      - POSTGRES_DB=gitea
    volumes:
      - ./postgres:/var/lib/postgresql/data

Kubernetes

Use official Helm chart:

helm repo add gitea https://dl.gitea.io/charts/
helm install gitea gitea/gitea

Reverse Proxy Configuration (Nginx)

server {
    listen 80;
    server_name gitea.example.com;

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

    location /ssh/ {
        proxy_pass http://localhost:2222;
        proxy_set_header Host $host;
        ssh-session-id $remote_addr;
    }
}

Database Initialization

Gitea auto-initializes database on first run. For manual setup:

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

6. Troubleshooting

Common Issues

1. Database Connection Errors

Symptoms: "database is locked" (SQLite), "connection refused" (MySQL/Postgres)

Solutions:

SQLite: Ensure no other process is accessing the database. Use sqlite_unlock_notify tag.
MySQL/Postgres: Verify credentials, host, and port in app.ini. Check firewall rules.
Ensure database exists and user has proper permissions.

2. Permission Issues

Symptoms: "permission denied" when accessing repositories

Solutions:

# Fix directory ownership
sudo chown -R gitea:gitea /var/lib/gitea
sudo chmod -R 750 /var/lib/gitea/data

3. SSH Not Working

Symptoms: Cannot clone via SSH, "connection refused"

Solutions:

Verify SSH port (default 22) is open and not conflicting
Check START_SSH_SERVER setting in app.ini
Ensure authorized_keys file exists in data/ssh/
Test SSH manually:
```
ssh -p 2222 git@localhost
```

4. Frontend Not Loading

Symptoms: Blank page, missing CSS/JS

Solutions:

If built from source without Node.js, ensure TAGS="bindata" was used
Check browser console for 404 errors on static files
Verify ROOT_URL in app.ini matches access URL

5. High Memory Usage

Symptoms: Gitea process using excessive RAM

Solutions:

Increase system swap space
Limit repository cache in app.ini:
```
[cache]
ADAPTER = memory
INTERVAL = 60
```
Consider using Redis adapter for cache

6. Migration from Other Git Services

Use built-in migration tools:

In web UI: Admin → Migrate Repository
Or via API: POST /repos/migrate
For GitHub/GitLab: Use OAuth integration for user migration

Logs

Default log location: log/gitea.log

Increase verbosity in app.ini:

[log]
MODE = console,file
LEVEL = Debug

Health Checks

# API health endpoint
curl http://localhost:3000/api/healthz

# Check database connectivity
./gitea admin doctor

Reset Admin Password

# Reset via CLI (if you have DB access)
./gitea admin user password --username admin --password newpassword

Getting Help

Note: This guide covers basic deployment. For advanced configurations (LDAP, OAuth2, CI/CD runners, package registry), refer to the official documentation.

How to Deploy & Use gitea

Gitea Deployment & Usage Guide

1. Prerequisites

System Requirements

Required Software

Optional Tools

2. Installation

From Binary (Recommended for Production)

From Source (Development)

Using Docker

3. Configuration

Initial Setup

Configuration File (app.ini)

Environment Variables

SSH Configuration

4. Build & Run

Development Run

Production Run

5. Deployment

Recommended Platforms

Docker Compose (All-in-One)

Kubernetes

Reverse Proxy Configuration (Nginx)

Database Initialization

6. Troubleshooting

Common Issues

1. Database Connection Errors

2. Permission Issues

3. SSH Not Working

4. Frontend Not Loading

5. High Memory Usage

6. Migration from Other Git Services

Logs

Health Checks

Reset Admin Password

Getting Help

Configuration File (`app.ini`)