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

# 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

# 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

# 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

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

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

# 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

# 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

# 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

# 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

# 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

# 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

# Secure internal access
https://calypso.tail.vish.gg:3052

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

CI/CD Integration

# 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

# 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

🔐 OAuth2 Single Sign-On (Authentik)

Gitea is configured with Authentik OAuth2 for SSO while keeping local admin login working.

Authentication Methods

1. Local Login - Username/password form
2. OAuth2 SSO - "Sign in with Authentik" button

Authentik Configuration

Setting	Value
Provider Name	Gitea OAuth2
Client ID	7KamS51a0H7V8HyIsfMKNJ8COstZEFh4Z8Em6ZhO
Redirect URI	https://git.vish.gg/user/oauth2/authentik/callback
Discovery URL	https://sso.vish.gg/application/o/gitea/.well-known/openid-configuration

Gitea Admin Setup

1. Go to Site Administration → Authentication Sources
2. Click Add Authentication Source
3. Select OAuth2
4. Configure:
   • Authentication Name: authentik
   • OAuth2 Provider: OpenID Connect
   • Client ID: (from Authentik)
   • Client Secret: (from Authentik)
   • OpenID Connect Auto Discovery URL: https://sso.vish.gg/application/o/gitea/.well-known/openid-configuration
5. Save

Important: Scope Mappings

The Authentik provider must have these scope mappings configured:

• authentik default OAuth Mapping: OpenID 'openid'
• authentik default OAuth Mapping: OpenID 'email'
• authentik default OAuth Mapping: OpenID 'profile'

Without these, users will get login errors.

Status

• OAuth2: ✅ Working
• Local Login: ✅ Working

📚 Additional Resources

• Official Documentation: Gitea Documentation
• Docker Hub: Gitea Docker Image
• Community: Gitea Discourse
• API Documentation: Gitea API
• Authentik Integration: Authentik Gitea Docs

🔗 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: 2025-11-17
Configuration Source: Calypso/gitea-server.yaml
External Access: https://git.vish.gg (web), ssh://git@external-ip:2222 (SSH)