Portainer/gitea

Gitea - Servidor Git Autoalojado

Gitea es un servidor Git ligero y autoalojado, similar a GitHub o GitLab.

📋 Descripción

Este stack despliega Gitea con:

• Base de datos PostgreSQL
• Servidor SSH para operaciones Git
• Gitea Actions (CI/CD similar a GitHub Actions)
• Act Runner para ejecutar pipelines
• Integración con Traefik y Authentik

🚀 Despliegue

Prerequisitos

1. Red Docker: Asegúrate de que la red proxy existe
2. Registro DNS: Configura el registro A para tu dominio Gitea
3. Puerto SSH: El puerto SSH debe estar disponible (por defecto 222)

Desde Portainer

1. Ve a Stacks → Add stack
2. Nombre: gitea
3. Selecciona Repository o Git repository
4. Configura:
   • Repository URL: <tu-repositorio>
   • Repository reference: main
   • Compose path: gitea/docker-compose.yml
5. Carga el archivo de variables de entorno: gitea/stack.env
6. Haz clic en Deploy the stack

Variables de Entorno Importantes

Edita el archivo stack.env:

# Imágenes
GITEA_IMAGE=gitea/gitea:latest
GITEA_POSTGRES_IMAGE=postgres:16
GITEA_RUNNER_IMAGE=gitea/act_runner:latest

# Base de datos
GITEA_DB_PASSWORD=tu-password-seguro-aleatorio

# Dominios
GITEA_DOMAIN=git.tudominio.com
GITEA_ROOT_URL=https://git.tudominio.com

# SSH
GITEA_SSH_DOMAIN=git.tudominio.com
GITEA_SSH_PORT=222

# Gitea Actions Runner
GITEA_RUNNER_REGISTRATION_TOKEN=tu-token-de-registro

⚙️ Configuración Post-Instalación

1. Primer Acceso

1. Accede a https://git.tudominio.com
2. Completa la configuración inicial:
   • Base de datos: Ya está configurada (PostgreSQL)
   • Configuración del servidor: Usa los valores predefinidos
   • Importante: Crea la cuenta de administrador en este paso
3. Haz clic en Install Gitea

2. Configurar Gitea Actions

Para habilitar CI/CD con Gitea Actions:

Paso 1: Generar Token de Registro

1. Accede a Gitea como administrador
2. Ve a Site Administration → Actions → Runners
3. Haz clic en Create new Runner
4. Copia el Registration Token

Paso 2: Actualizar el Stack

1. Edita el archivo stack.env
2. Añade el token:

   GITEA_RUNNER_REGISTRATION_TOKEN=tu-token-copiado
   

3. Actualiza el stack en Portainer

Paso 3: Verificar el Runner

1. En Gitea, ve a Site Administration → Actions → Runners
2. Deberías ver el runner registrado y activo
3. Nombre del runner: act-runner-docker (o el configurado en GITEA_RUNNER_NAME)

3. Configurar SSH

Para usar Git con SSH:

# Clonar repositorio con SSH
git clone ssh://git@git.tudominio.com:222/usuario/repositorio.git

# O configurar SSH en ~/.ssh/config
Host git.tudominio.com
    HostName git.tudominio.com
    Port 222
    User git
    IdentityFile ~/.ssh/id_ed25519

4. Integración con Authentik (SSO)

Este stack tiene una configuración especial para Authentik:

Rutas Protegidas

• /user/login - Página de login (protegida con SSO)
• /explore - Explorar repositorios públicos (protegida)
• /TheHomelessSherlock - Perfil de usuario específico (protegido)

Rutas Públicas

• Repositorios públicos accesibles sin autenticación
• API Git (clone, pull, push) funciona sin SSO

Configurar OAuth con Authentik

1. En Authentik, crea una aplicación para Gitea:

   • Tipo: OAuth2/OpenID Provider
   • Client type: Confidential
   • Redirect URIs: https://git.tudominio.com/user/oauth2/authentik/callback

2. En Gitea, ve a Site Administration → Authentication Sources → Add Authentication Source

3. Tipo: OAuth2

4. Configura:

   • Provider: OpenID Connect
   • Client ID: (de Authentik)
   • Client Secret: (de Authentik)
   • OpenID Connect Auto Discovery URL: https://auth.tudominio.com/application/o/gitea/.well-known/openid-configuration

5. Actualiza las variables en stack.env:

   GITEA_ENABLE_OPENID_SIGNIN=true
   GITEA_ENABLE_OPENID_SIGNUP=true
   GITEA_DISABLE_LOGIN_FORM=false  # Mantén false para permitir login local también
   

🔧 Configuración Avanzada

Personalización de la UI

Las siguientes opciones están preconfiguradas:

• Tema por defecto: Oscuro (gitea-dark)
• Registro deshabilitado: Solo administradores pueden crear usuarios (o usar SSO)
• Visibilidad por defecto: Privada
• Requiere login para ver: Activado

Para cambiar estas opciones, edita stack.env y actualiza el stack.

Limitar Acceso por Organización

GITEA_DEFAULT_ALLOW_CREATE_ORGANIZATION=false
GITEA_DEFAULT_ORG_VISIBILITY=private

Notificaciones por Email

Añade al archivo stack.env:

GITEA__mailer__ENABLED=true
GITEA__mailer__FROM=gitea@tudominio.com
GITEA__mailer__PROTOCOL=smtp
GITEA__mailer__SMTP_ADDR=smtp.tudominio.com
GITEA__mailer__SMTP_PORT=587
GITEA__mailer__USER=gitea@tudominio.com
GITEA__mailer__PASSWD=tu-password-smtp

Configurar Webhooks

Gitea soporta webhooks para integración con otros servicios:

1. Ve a tu repositorio → Settings → Webhooks
2. Añade un webhook con la URL de destino
3. Selecciona los eventos que quieres recibir

Ejemplo de Workflow con Gitea Actions

Crea .gitea/workflows/build.yml en tu repositorio:

name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm install
      
      - name: Build
        run: npm run build
      
      - name: Test
        run: npm test

🛠️ Troubleshooting

No puedo hacer push/pull por SSH

1. Verifica que el puerto SSH está abierto:

   telnet git.tudominio.com 222
   

2. Verifica tu clave SSH:

   ssh -T git@git.tudominio.com -p 222
   

3. Añade tu clave SSH en Gitea:

   • Ve a Settings → SSH / GPG Keys → Add Key

El runner de Actions no se registra

1. Verifica los logs:

   docker logs gitea-act-runner
   

2. Verifica que el token es correcto en stack.env

3. Regenera el token en Gitea si es necesario

4. Asegúrate de que el runner puede comunicarse con Gitea:

   docker exec gitea-act-runner ping gitea
   

Error de permisos con volúmenes

Si usas SELinux, los volúmenes ya tienen :Z:

# Si persisten problemas
sudo chcon -Rt svirt_sandbox_file_t /opt/gitea/data
sudo chcon -Rt svirt_sandbox_file_t /opt/gitea/postgres

OAuth con Authentik no funciona

1. Verifica que la Redirect URI en Authentik es exacta
2. Comprueba que el Discovery URL es accesible desde el contenedor:

   docker exec gitea curl https://auth.tudominio.com/application/o/gitea/.well-known/openid-configuration
   

3. Revisa los logs de Gitea: docker logs gitea

La base de datos no inicia

1. Verifica los logs de PostgreSQL:

   docker logs gitea-postgres
   

2. Verifica los permisos del directorio de datos:

   ls -lh /opt/gitea/postgres
   

3. Si necesitas reiniciar desde cero:

   docker compose down
   sudo rm -rf /opt/gitea/postgres/*
   docker compose up -d
   

📚 Recursos Adicionales

• Documentación oficial de Gitea
• Gitea Actions
• Act Runner
• Migrar desde GitHub/GitLab

🔒 Seguridad

• SSH: Usa claves SSH en lugar de passwords para Git
• 2FA: Habilita autenticación de dos factores en tu cuenta
• Tokens: Usa tokens de acceso con permisos limitados para CI/CD
• Webhooks: Verifica siempre las firmas de webhooks
• Backups: Realiza backups regulares de la base de datos y repositorios

💾 Backups

Backup de la Base de Datos

# Backup completo
docker exec gitea-postgres pg_dump -U gitea gitea > gitea_backup_$(date +%Y%m%d).sql

# Restaurar
cat gitea_backup_YYYYMMDD.sql | docker exec -i gitea-postgres psql -U gitea gitea

Backup de Repositorios y Datos

# Backup completo de datos
sudo tar -czf gitea-data-backup-$(date +%Y%m%d).tar.gz /opt/gitea/data

# Restaurar
sudo tar -xzf gitea-data-backup-YYYYMMDD.tar.gz -C /

Backup Automático

Considera usar el comando nativo de Gitea:

docker exec -u git gitea gitea dump -c /data/gitea/conf/app.ini

Esto crea un archivo gitea-dump-*.zip con todo lo necesario para restaurar.

🔄 Actualizaciones

1. Backup primero: Siempre haz backup antes de actualizar
2. Actualiza la versión en stack.env:

   GITEA_IMAGE=gitea/gitea:1.21.0
   

3. Actualiza el stack en Portainer
4. Verifica los logs: docker logs gitea
5. Prueba que todo funciona correctamente

📊 Monitoreo

Ver Estadísticas

• Accede a Site Administration → Dashboard
• Revisa usuarios, repositorios, organizaciones, etc.

Logs

# Logs de Gitea
docker logs -f gitea

# Logs de PostgreSQL
docker logs -f gitea-postgres

# Logs del Runner
docker logs -f gitea-act-runner

Métricas

Gitea soporta exportación de métricas para Prometheus:

1. Habilita métricas en stack.env:

   GITEA__metrics__ENABLED=true
   GITEA__metrics__TOKEN=tu-token-secreto
   

2. Las métricas estarán disponibles en: https://git.tudominio.com/metrics?token=tu-token-secreto