Sanitized mirror from private repository - 2026-03-21 11:14:37 UTC
This commit is contained in:
Gitea Mirror Bot
369
docs/services/individual/gitea.md
Normal file
369
docs/services/individual/gitea.md
Normal file
@@ -0,0 +1,369 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user