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>
This commit is contained in:
kappa
552
gitea-setup.md
Normal file
552
gitea-setup.md
Normal file
@@ -0,0 +1,552 @@
|
||||
# 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 (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)
|
||||
|
||||
```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.
|
||||
Reference in New Issue
Block a user