TheHomelessSherlock/Portainer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Portainer/gitea/README.md
Eduardo David Paredes Vara 4ac3881958 Initial clean commit (history purged)
2025-12-03 17:15:06 +00:00

9.3 KiB
Raw Permalink Blame History

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

🔒 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

Reference in New Issue View Git Blame Copy Permalink