runbooks/gitea-setup.md

Gitea Docker Compose Setup

A production-ready Gitea deployment using Docker Compose with PostgreSQL, optimized for NAS systems and self-hosted environments.

🚀 Quick Start

1. Clone or download this repository
2. Run the setup script:

   ./setup-gitea.sh
   

3. Start Gitea:

   docker-compose up -d
   

4. Access Gitea at: http://localhost:3000

📋 Prerequisites

Required Software

• Docker Engine (20.10+)
• Docker Compose (2.0+)
• OpenSSL (for generating secure keys)
• Bash (for setup scripts)

System Requirements

• RAM: Minimum 2GB, recommended 4GB+
• Storage: Minimum 10GB free space
• Network: Ports 3000 (HTTP) and 2222 (SSH) available

Installation Commands

Ubuntu/Debian:

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Log out and back in to apply group changes

macOS:

# Install Docker Desktop from https://docker.com/products/docker-desktop
# Or via Homebrew:
brew install --cask docker

🏗️ Architecture

Services

• gitea: Main Gitea application (rootless container)
• gitea-db: PostgreSQL 15 database
• gitea-runner: Optional Gitea Actions runner

Volumes

• gitea-data: Application data and repositories
• gitea-config: Configuration files
• gitea-db-data: PostgreSQL data
• gitea-runner-data: Actions runner data

Network

• gitea-network: Isolated bridge network with custom subnet

⚙️ Configuration

Environment Variables

The setup is configured through a .env file. Key settings include:

# Domain Configuration
GITEA_DOMAIN=your-domain.com
GITEA_ROOT_URL=https://your-domain.com

# Port Configuration
GITEA_HTTP_PORT=3000
GITEA_SSH_PORT=2222

# Security - 파일 기반 Secret 권장 (환경변수 노출 방지)
# docker-compose에서 secrets 사용 시:
# GITEA__security__SECRET_KEY__FILE=/run/secrets/gitea_secret_key
# GITEA__security__INTERNAL_TOKEN__FILE=/run/secrets/gitea_internal_token

# 환경변수 방식 (개발용)
GITEA_SECRET_KEY=your_secret_key
GITEA_INTERNAL_TOKEN=your_internal_token

# Database
POSTGRES_PASSWORD=secure_password

# Admin Account
GITEA_ADMIN_USER=admin
GITEA_ADMIN_EMAIL=admin@your-domain.com
GITEA_ADMIN_PASSWORD=secure_password

보안 강화 설정 (app.ini)

프로덕션 환경에서 아래 설정을 app.ini 또는 환경변수로 추가:

[security]
; 비밀번호 정책 강화
MIN_PASSWORD_LENGTH = 10
PASSWORD_COMPLEXITY = lower,upper,digit
PASSWORD_HASH_ALGO = argon2

; Git Hooks 비활성화 (보안 강화)
DISABLE_GIT_HOOKS = true

; 리버스 프록시 신뢰 설정
REVERSE_PROXY_TRUSTED_PROXIES = 127.0.0.0/8,::1/128

; Secret 파일 기반 관리 (권장)
SECRET_KEY_URI = file:/etc/gitea/secret_key
INTERNAL_TOKEN_URI = file:/etc/gitea/internal_token

[service]
; 회원가입 비활성화 (필요시)
DISABLE_REGISTRATION = true
; 로그인 필수
REQUIRE_SIGNIN_VIEW = true
; 이메일 비공개 기본값
DEFAULT_KEEP_EMAIL_PRIVATE = true

[repository.signing]
; 커밋 서명 설정
SIGNING_KEY = default
INITIAL_COMMIT = always

Docker Secrets 사용 (프로덕션 권장)

# docker-compose.yml
services:
  gitea:
    image: gitea/gitea:latest-rootless
    environment:
      - GITEA__security__SECRET_KEY__FILE=/run/secrets/gitea_secret_key
      - GITEA__security__INTERNAL_TOKEN__FILE=/run/secrets/gitea_internal_token
      - GITEA__database__PASSWD__FILE=/run/secrets/db_password
    secrets:
      - gitea_secret_key
      - gitea_internal_token
      - db_password

secrets:
  gitea_secret_key:
    file: ./secrets/secret_key
  gitea_internal_token:
    file: ./secrets/internal_token
  db_password:
    file: ./secrets/db_password

# Secret 파일 생성
mkdir -p secrets
openssl rand -base64 32 > secrets/secret_key
openssl rand -base64 32 > secrets/internal_token
openssl rand -base64 24 > secrets/db_password
chmod 600 secrets/*

Advanced Configuration

For advanced settings, modify:

• docker-compose.yml: Service configuration, resource limits, environment variables
• gitea-app.ini.template: Detailed Gitea configuration reference
• .env: Environment-specific settings

🚀 Installation Guide

Method 1: Automated Setup (Recommended)

# 1. Download the setup files
git clone <repository-url> gitea-setup
cd gitea-setup

# 2. Run interactive setup
./setup-gitea.sh

# 3. Start services
docker-compose up -d

# 4. Check status
docker-compose ps
docker-compose logs -f gitea

Method 2: Manual Setup

# 1. Create directories
mkdir -p gitea-{data,config,db-data,runner-data} backups

# 2. Copy environment file
cp .env.example .env

# 3. Edit configuration
nano .env  # Update all required values

# 4. Generate secure keys
openssl rand -base64 32  # Use for GITEA_SECRET_KEY
openssl rand -base64 32  # Use for GITEA_INTERNAL_TOKEN

# 5. Start services
docker-compose up -d

🔐 Security Configuration

SSL/TLS Setup with Reverse Proxy

Nginx Configuration:

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;
    
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    
    client_max_body_size 512M;
    
    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;
    }
}

Traefik Configuration:

# docker-compose.override.yml
services:
  gitea:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.gitea.rule=Host(`your-domain.com`)"
      - "traefik.http.routers.gitea.tls.certresolver=letsencrypt"
      - "traefik.http.services.gitea.loadbalancer.server.port=3000"

SSH Configuration

Host SSH Configuration (recommended):

# Add to /etc/ssh/sshd_config
Match User git
    AllowTcpForwarding no
    AllowAgentForwarding no
    PermitTTY no
    X11Forwarding no

Container SSH (current setup):

• SSH server runs inside Gitea container
• Exposed on port 2222
• User authentication via Gitea SSH keys

Firewall Configuration

# Ubuntu/Debian (ufw)
sudo ufw allow 3000/tcp comment 'Gitea HTTP'
sudo ufw allow 2222/tcp comment 'Gitea SSH'

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

🗄️ Backup & Restore

Automated Backup

# Full backup (recommended)
./backup-gitea.sh --full

# Database only
./backup-gitea.sh --database-only

# Custom retention and compression
./backup-gitea.sh --full --retention 90 --compress 9

Backup Schedule

Crontab example:

# Daily backup at 2 AM, keep for 30 days
0 2 * * * /path/to/gitea-setup/backup-gitea.sh --full --retention 30

# Weekly full backup, keep for 1 year
0 2 * * 0 /path/to/gitea-setup/backup-gitea.sh --full --retention 365

Restore from Backup

# Restore from full backup
./restore-gitea.sh backups/gitea_backup_20240101_120000.tar.gz

# Restore database only
./restore-gitea.sh --database-only backup_directory/

# Restore with current data backup
./restore-gitea.sh --backup-current latest_backup.tar.gz

🔄 Maintenance

Update Gitea

# Check for updates
./update-gitea.sh --check-only

# Update to latest version
./update-gitea.sh

# Update to specific version
./update-gitea.sh 1.21.5

Monitor Services

# Check service status
docker-compose ps

# View logs
docker-compose logs -f gitea
docker-compose logs -f gitea-db

# Monitor resources
docker-compose top
docker stats

Database Maintenance

# Access database
docker-compose exec gitea-db psql -U gitea -d gitea

# Database backup
docker-compose exec gitea-db pg_dump -U gitea -d gitea > backup.sql

# Database restore
docker-compose exec -T gitea-db psql -U gitea -d gitea < backup.sql

🔧 Troubleshooting

Common Issues

1. Permission Errors

# Fix directory permissions
sudo chown -R 1000:1000 gitea-data gitea-config
sudo chmod -R 755 gitea-data gitea-config

2. Database Connection Issues

# Check database logs
docker-compose logs gitea-db

# Test database connection
docker-compose exec gitea-db pg_isready -U gitea -d gitea

3. SSH Access Issues

# Check SSH configuration
docker-compose exec gitea cat /etc/gitea/app.ini | grep -A 5 "\[server\]"

# Test SSH connection
ssh -T git@localhost -p 2222

4. Memory/Resource Issues

# Check resource usage
docker stats

# Adjust resource limits in docker-compose.yml
services:
  gitea:
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '1.0'

Log Analysis

# Application logs
docker-compose logs --tail=100 -f gitea

# Database logs
docker-compose logs --tail=100 -f gitea-db

# System logs (Ubuntu/Debian)
sudo journalctl -u docker --tail=100 -f

Health Checks

# Service health
docker-compose exec gitea curl -f http://localhost:3000/api/healthz

# Database health
docker-compose exec gitea-db pg_isready -U gitea -d gitea

🎯 Performance Optimization

NAS-Specific Optimizations

1. Storage Configuration:

# Use external SSD for better performance
volumes:
  gitea-data:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /mnt/ssd/gitea-data

2. Resource Limits:

services:
  gitea:
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '1.0'
        reservations:
          memory: 512M
          cpus: '0.5'

3. Database Tuning:

# Add to docker-compose.yml under gitea-db environment
POSTGRES_INITDB_ARGS: "--encoding=UTF8 --lc-collate=C --lc-ctype=C"

Network Optimization

# Custom network configuration
networks:
  gitea-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16

📊 Monitoring

Basic Monitoring

# Resource usage
docker stats --no-stream

# Disk usage
du -sh gitea-data/ gitea-db-data/

# Service health
curl -f http://localhost:3000/api/healthz

Advanced Monitoring with Prometheus

# Add to docker-compose.yml
  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3001:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

🔌 Gitea Actions (CI/CD)

Enable Actions Runner

# Start with actions profile
docker-compose --profile actions up -d

# Or enable in existing deployment
docker-compose up -d gitea-runner

Runner Configuration

1. Generate Registration Token:

   • Go to Gitea Admin → Site Administration → Actions → Runners
   • Click "Create new Runner"
   • Copy the registration token

2. Add Token to Environment:

   echo "GITEA_RUNNER_TOKEN=your_token_here" >> .env
   docker-compose restart gitea-runner
   

Action Examples

.gitea/workflows/ci.yml:

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tests
        run: |
          echo "Running tests..."
          # Add your test commands here

📚 Additional Resources

Official Documentation

• Gitea Documentation
• Docker Compose Reference
• PostgreSQL Documentation

Community Resources

• Gitea Community
• Docker Community

Migration Guides

• GitHub to Gitea Migration
• GitLab to Gitea Migration

🆘 Support

Getting Help

1. Check logs first:

   docker-compose logs -f gitea
   

2. Review common issues in this README

3. Search existing issues:

   • Gitea Issues
   • Community Discussions

4. Create detailed bug report with:

   • Gitea version
   • Docker version
   • Operating system
   • Error logs
   • Steps to reproduce

Script Help

All scripts include built-in help:

./setup-gitea.sh --help
./backup-gitea.sh --help
./restore-gitea.sh --help
./update-gitea.sh --help

📄 License

This setup configuration is provided under the MIT License. Gitea itself is licensed under the MIT License.

🙏 Acknowledgments

• Gitea Team for creating an excellent Git service
• Docker Community for containerization platform
• PostgreSQL Team for the reliable database

---

Happy Self-Hosting! 🎉

For questions or improvements, please open an issue or pull request.