Files

kappa 49fe96775a Add 5 more runbooks

- aws-ses-setup.md: AWS SES email configuration
- anvil-ses-final-setup.md: Anvil SES final setup
- n8n-setup-guide.md: n8n workflow automation
- gitea-setup.md: Gitea server installation
- cloudflare-vault-integration.md: Cloudflare + Vault integration

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-16 00:39:06 +09:00

11 KiB

Raw Blame History

Gitea Docker Compose Setup

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

🚀 Quick Start

Clone or download this repository
Run the setup script:
```
./setup-gitea.sh
```
Start Gitea:
```
docker-compose up -d
```
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 (automatically generated)
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

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

Generate Registration Token:
- Go to Gitea Admin → Site Administration → Actions → Runners
- Click "Create new Runner"
- Copy the registration token

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

Community Resources

Migration Guides

🆘 Support

Getting Help

Check logs first:
```
docker-compose logs -f gitea
```
Review common issues in this README
Search existing issues:
- Gitea Issues
- Community Discussions
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.

11 KiB Raw Blame History