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:**
   ```bash
   ./setup-gitea.sh
   ```
3. **Start Gitea:**
   ```bash
   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:**
```bash
# 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:**
```bash
# 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:

```bash
# 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` 또는 환경변수로 추가:

```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 사용 (프로덕션 권장)

```yaml
# 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
```

```bash
# 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)

```bash
# 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

```bash
# 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:**
```nginx
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:**
```yaml
# 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):**
```bash
# 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

```bash
# 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

```bash
# 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:**
```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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**
```bash
# Fix directory permissions
sudo chown -R 1000:1000 gitea-data gitea-config
sudo chmod -R 755 gitea-data gitea-config
```

**2. Database Connection Issues**
```bash
# 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**
```bash
# 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**
```bash
# Check resource usage
docker stats

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

### Log Analysis

```bash
# 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

```bash
# 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:**
```yaml
# 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:**
```yaml
services:
  gitea:
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '1.0'
        reservations:
          memory: 512M
          cpus: '0.5'
```

**3. Database Tuning:**
```bash
# Add to docker-compose.yml under gitea-db environment
POSTGRES_INITDB_ARGS: "--encoding=UTF8 --lc-collate=C --lc-ctype=C"
```

### Network Optimization

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

## 📊 Monitoring

### Basic Monitoring

```bash
# 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

```yaml
# 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

```bash
# 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:**
   ```bash
   echo "GITEA_RUNNER_TOKEN=your_token_here" >> .env
   docker-compose restart gitea-runner
   ```

### Action Examples

**.gitea/workflows/ci.yml:**
```yaml
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](https://docs.gitea.com/)
- [Docker Compose Reference](https://docs.docker.com/compose/)
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)

### Community Resources
- [Gitea Community](https://github.com/go-gitea/gitea/discussions)
- [Docker Community](https://forums.docker.com/)

### Migration Guides
- [GitHub to Gitea Migration](https://docs.gitea.com/usage/migrate-from-github/)
- [GitLab to Gitea Migration](https://docs.gitea.com/usage/migrate-from-gitlab/)

## 🆘 Support

### Getting Help

1. **Check logs first:**
   ```bash
   docker-compose logs -f gitea
   ```

2. **Review common issues** in this README

3. **Search existing issues:**
   - [Gitea Issues](https://github.com/go-gitea/gitea/issues)
   - [Community Discussions](https://github.com/go-gitea/gitea/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:
```bash
./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](https://gitea.io/) for creating an excellent Git service
- [Docker Community](https://docker.com/) for containerization platform
- [PostgreSQL Team](https://postgresql.org/) for the reliable database

---

**Happy Self-Hosting!** 🎉

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