homelab-optimized/docs/services/individual/gitea.md

# Gitea - Self-Hosted Git Service

**🟡 Development Service**

## 📋 Service Overview

| Property | Value |
|----------|-------|
| **Service Name** | Gitea |
| **Host** | Calypso (192.168.0.250) |
| **Category** | Development |
| **Difficulty** | 🟡 |
| **Docker Images** | `gitea/gitea:latest`, `postgres:16-bookworm` |
| **Compose File** | `Calypso/gitea-server.yaml` |
| **Directory** | `Calypso/` |
| **External Domain** | `git.vish.gg` |

## 🎯 Purpose

Gitea is a lightweight, self-hosted Git service that provides a web-based interface for Git repository management, issue tracking, pull requests, and team collaboration. It's a complete DevOps platform similar to GitHub but running on your own infrastructure.

## 🌐 Access Information

### **Web Interface**
- **External Access**: https://git.vish.gg
- **Internal Access**: http://calypso.tail.vish.gg:3052
- **Local Network**: http://192.168.0.250:3052

### **SSH Git Access**
- **External SSH**: `ssh://git@git.vish.gg:2222`
- **Internal SSH**: `ssh://git@192.168.0.250:2222`
- **Tailscale SSH**: `ssh://git@calypso.tail.vish.gg:2222`

## 🔌 Port Forwarding Configuration

### **Router Port Forward**
| Service | External Port | Internal Port | Protocol | Purpose |
|---------|---------------|---------------|----------|---------|
| **Gitea SSH** | 2222 | 2222 | All | Git SSH operations |

### **Container Port Mappings**
| Host Port | Container Port | Purpose |
|-----------|----------------|---------|
| 3052 | 3000 | Web interface |
| 2222 | 22 | SSH Git access |

### **External Git Operations**
```bash
# Clone repository via external SSH
git clone ssh://git@git.vish.gg:2222/username/repository.git

# Add external remote
git remote add origin ssh://git@git.vish.gg:2222/username/repository.git

# Push to external repository
git push origin main

# Clone via HTTPS (web interface)
git clone https://git.vish.gg/username/repository.git
```

## 🚀 Quick Start

### Prerequisites
- Docker and Docker Compose installed
- PostgreSQL database container
- Port forwarding configured for SSH access
- Domain name pointing to external IP (optional)

### Deployment
```bash
# Navigate to service directory
cd Calypso/

# Start Gitea and database
docker-compose -f gitea-server.yaml up -d

# Check service status
docker-compose -f gitea-server.yaml ps

# View logs
docker-compose -f gitea-server.yaml logs -f
```

### Initial Setup
```bash
# Access web interface
http://192.168.0.250:3052

# Complete initial setup wizard:
1. Database configuration (PostgreSQL)
2. General settings (site title, admin account)
3. Optional settings (email, security)
4. Create admin account
```

## 🔧 Configuration

### Docker Compose Services

#### **Gitea Web Service**
```yaml
web:
  image: gitea/gitea:latest
  container_name: Gitea
  ports:
    - 3052:3000  # Web interface
    - 2222:22    # SSH Git access
  environment:
    - USER_UID=1026
    - USER_GID=100
    - ROOT_URL=https://git.vish.gg
    - GITEA__database__DB_TYPE=postgres
    - GITEA__database__HOST=gitea-db:5432
```

#### **PostgreSQL Database**
```yaml
db:
  image: postgres:16-bookworm
  container_name: Gitea-DB
  environment:
    - POSTGRES_DB=gitea
    - POSTGRES_USER=giteauser
    - POSTGRES_PASSWORD="REDACTED_PASSWORD"
  healthcheck:
    test: ["CMD", "pg_isready", "-q", "-d", "gitea", "-U", "giteauser"]
```

### Key Environment Variables
| Variable | Value | Description |
|----------|-------|-------------|
| `ROOT_URL` | `https://git.vish.gg` | External access URL |
| `USER_UID` | `1026` | User ID for file permissions |
| `USER_GID` | `100` | Group ID for file permissions |
| `POSTGRES_DB` | `gitea` | Database name |
| `POSTGRES_USER` | `giteauser` | Database username |

### Volume Mappings
| Host Path | Container Path | Purpose |
|-----------|----------------|---------|
| `/volume1/docker/gitea/data` | `/data` | Gitea application data |
| `/volume1/docker/gitea/db` | `/var/lib/postgresql/data` | PostgreSQL database |

## 🔒 Security Considerations

### **External Exposure Assessment**
- **✅ SSH Access**: Port 2222 with key-based authentication
- **⚠️ Web Interface**: Should be behind HTTPS reverse proxy
- **✅ Database**: Internal container network only
- **✅ Security Options**: `no-new-privileges:true` enabled

### **Security Recommendations**
```bash
# 1. SSH Key Authentication
- Disable password authentication
- Use SSH keys for all Git operations
- Regularly rotate SSH keys
- Monitor SSH access logs

# 2. Web Interface Security
- Enable 2FA for all users
- Use strong passwords
- Configure HTTPS with valid certificates
- Implement rate limiting

# 3. Database Security
- Regular database backups
- Strong database passwords
- Database access restricted to container network
- Monitor database logs

# 4. Access Control
- Configure user permissions carefully
- Use organization/team features for access control
- Regular audit of user accounts and permissions
- Monitor repository access logs
```

## 🚨 Troubleshooting

### **Common Issues**

#### **SSH Git Access Not Working**
```bash
# Test SSH connection
ssh -p 2222 git@git.vish.gg

# Check SSH key configuration
ssh-add -l
cat ~/.ssh/id_rsa.pub

# Verify port forwarding
nmap -p 2222 git.vish.gg

# Check Gitea SSH settings
docker-compose -f gitea-server.yaml logs web | grep ssh
```

#### **Web Interface Not Accessible**
```bash
# Check container status
docker-compose -f gitea-server.yaml ps

# Verify port binding
netstat -tulpn | grep 3052

# Check logs for errors
docker-compose -f gitea-server.yaml logs web
```

#### **Database Connection Issues**
```bash
# Check database health
docker-compose -f gitea-server.yaml logs db

# Test database connection
docker-compose -f gitea-server.yaml exec db pg_isready -U giteauser

# Verify database credentials
docker-compose -f gitea-server.yaml exec web env | grep POSTGRES
```

### **Performance Optimization**
```bash
# Monitor resource usage
docker stats Gitea Gitea-DB

# Optimize PostgreSQL settings
# Edit postgresql.conf for better performance
# Increase shared_buffers, work_mem

# Configure Gitea caching
# Enable Redis cache for better performance
# Configure Git LFS for large files
```

## 📊 Resource Requirements

### **Recommended Resources**
- **Minimum RAM**: 2GB total (1GB Gitea + 1GB PostgreSQL)
- **Recommended RAM**: 4GB+ for production use
- **CPU**: 2+ cores for multiple concurrent users
- **Storage**: 50GB+ for repositories and database
- **Network**: Moderate bandwidth for Git operations

### **Scaling Considerations**
- **Small teams (1-10 users)**: Default configuration sufficient
- **Medium teams (10-50 users)**: Increase memory allocation
- **Large teams (50+ users)**: Consider external PostgreSQL
- **Enterprise**: Implement clustering and load balancing

## 🔍 Health Monitoring

### **Service Health Checks**
```bash
# Check web interface health
curl -f http://192.168.0.250:3052/api/healthz

# Database health check
docker-compose -f gitea-server.yaml exec db pg_isready -U giteauser

# SSH service check
ssh -p 2222 git@192.168.0.250 info
```

### **Monitoring Metrics**
- **Active users**: Number of logged-in users
- **Repository count**: Total repositories hosted
- **Git operations**: Push/pull frequency and size
- **Database performance**: Query response times
- **Storage usage**: Repository and database disk usage

## 🌐 Integration with Homelab

### **Tailscale Access**
```bash
# Secure internal access
https://calypso.tail.vish.gg:3052

# SSH via Tailscale
ssh://git@calypso.tail.vish.gg:2222
```

### **CI/CD Integration**
```bash
# Gitea Actions (built-in CI/CD)
# Configure runners for automated builds
# Set up webhooks for external services
# Integrate with Docker registry

# External CI/CD
# Jenkins integration via webhooks
# GitHub Actions mirror
# GitLab CI/CD pipeline import
```

### **Backup Integration**
```bash
# Database backups
docker-compose -f gitea-server.yaml exec db pg_dump -U giteauser gitea > backup.sql

# Repository backups
rsync -av /volume1/docker/gitea/data/git/repositories/ /backup/gitea-repos/

# Automated backup scripts
# Schedule regular backups via cron
# Test backup restoration procedures
```

## 🔐 SSO / Authentik Integration

Gitea uses Authentik as an OAuth2/OIDC provider. Both local login and SSO are enabled.

### Authentication Methods
1. **Local Login** — Username/password (admin fallback)
2. **OAuth2 SSO** — "Sign in with Authentik" button on login page

### Configuration

| Setting | Value |
|---------|-------|
| **Authentik App Slug** | `gitea` |
| **Authentik Provider PK** | `2` |
| **Client ID** | `7KamS51a0H7V8HyIsfMKNJ8COstZEFh4Z8Em6ZhO` |
| **Redirect URIs** | `https://git.vish.gg/user/oauth2/authentik/callback`, `https://git.vish.gg/user/oauth2/Authentik/callback` |
| **Discovery URL** | `https://sso.vish.gg/application/o/gitea/.well-known/openid-configuration` |

> **Note:** Both lower and upper-case `authentik`/`Authentik` redirect URIs are registered in Authentik — Gitea sends the capitalised form (`Authentik`) based on the auth source name.

### To re-register the auth source (if lost)
```bash
docker exec -u git Gitea gitea admin auth add-oauth \
  --name 'Authentik' \
  --provider openidConnect \
  --key <client_id> \
  --secret <client_secret> \
  --auto-discover-url 'https://sso.vish.gg/application/o/gitea/.well-known/openid-configuration' \
  --scopes 'openid email profile'
```

### Status
- **OAuth2 SSO**: ✅ Working (added 2026-03-16)
- **Local Login**: ✅ Working
- **Admin user**: `Vish` / `admin@thevish.io`

## 📚 Additional Resources

- **Official Documentation**: [Gitea Documentation](https://docs.gitea.io/)
- **Docker Hub**: [Gitea Docker Image](https://hub.docker.com/r/gitea/gitea)
- **Community**: [Gitea Discourse](https://discourse.gitea.io/)
- **API Documentation**: [Gitea API](https://docs.gitea.io/en-us/api-usage/)
- **Authentik Integration**: [Authentik Gitea Docs](https://docs.goauthentik.io/integrations/services/gitea/)

## 🔗 Related Services

- **PostgreSQL**: Database backend
- **Nginx**: Reverse proxy for HTTPS
- **Docker Registry**: Container image storage
- **Jenkins**: CI/CD integration
- **Grafana**: Monitoring and metrics

---

*This documentation covers the complete Gitea setup including external SSH access and web interface configuration.*

**Last Updated**: 2026-03-16  
**Configuration Source**: `hosts/synology/calypso/gitea-server.yaml`  
**External Access**: `https://git.vish.gg` (web), `ssh://git@git.vish.gg:2222` (SSH)