⚠️ Importante: Usa comillas simples en el archivo .env si la contraseña contiene caracteres especiales. Ejemplo: DB_PASSWORD='tu_password_generado'

Despliegue con Portainer

Opción A: Git Repository (Recomendada)

Permite mantener la configuración actualizada automáticamente desde Git.

En Portainer, ve a Stacks → Add stack
Nombra el stack: gitea
Selecciona Git Repository
Configura:
- Repository URL: https://git.ictiberia.com/groales/gitea
- Repository reference: refs/heads/main
- Compose path: docker-compose.yml
- Additional paths: Solo para Traefik: docker-compose.override.traefik.yml.example
En Environment variables, añade:

Para Traefik:
```
DOMAIN_HOST=gitea.tudominio.com
DB_PASSWORD='tu_password_generado'
```
Para NPM:
```
DB_PASSWORD='tu_password_generado'
```
⚠️ Nota para NPM: No uses Additional paths, el docker-compose.yml base es suficiente.
Haz clic en Deploy the stack

Configuración de WebSocket

Traefik: Ya configurado en el override
NPM: Puede requerir activar WebSocket Support para push/pull en tiempo real

Opción B: Web Editor

Copia y pega el contenido consolidado según tu configuración de proxy.

En Portainer, ve a Stacks → Add stack
Nombra el stack: gitea
Selecciona Web editor
Copia el contenido según tu entorno:

📋 Despliegue con Traefik

services:
  gitea:
    container_name: gitea
    image: gitea/gitea:latest
    restart: unless-stopped
    environment:
      USER_UID: 1000
      USER_GID: 1000
      GITEA__database__DB_TYPE: postgres
      GITEA__database__HOST: gitea-db:5432
      GITEA__database__NAME: ${DB_NAME:-gitea}
      GITEA__database__USER: ${DB_USER:-gitea}
      GITEA__database__PASSWD: ${DB_PASSWORD}
      TZ: Europe/Madrid
    volumes:
      - gitea_data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    networks:
      - proxy
      - gitea-internal
    depends_on:
      - gitea-db
    labels:
      # HTTP → HTTPS redirect
      - "traefik.enable=true"
      - "traefik.http.routers.gitea-http.rule=Host(`${DOMAIN_HOST}`)"
      - "traefik.http.routers.gitea-http.entrypoints=web"
      - "traefik.http.routers.gitea-http.middlewares=redirect-to-https@docker"
      
      # HTTPS router
      - "traefik.http.routers.gitea.rule=Host(`${DOMAIN_HOST}`)"
      - "traefik.http.routers.gitea.entrypoints=websecure"
      - "traefik.http.routers.gitea.tls=true"
      - "traefik.http.routers.gitea.tls.certresolver=letsencrypt"
      - "traefik.http.routers.gitea.service=gitea-svc"
      - "traefik.http.services.gitea-svc.loadbalancer.server.port=3000"
      
      # Redirect middleware
      - "traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https"
      - "traefik.http.middlewares.redirect-to-https.redirectscheme.permanent=true"

  gitea-db:
    container_name: gitea-db
    image: postgres:18-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${DB_NAME:-gitea}
      POSTGRES_USER: ${DB_USER:-gitea}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - gitea_db:/var/lib/postgresql/data
    networks:
      - gitea-internal

volumes:
  gitea_data:
    name: gitea_data
  gitea_db:
    name: gitea_db

networks:
  proxy:
    external: true
  gitea-internal:
    name: gitea-internal

Variables de entorno necesarias:

DOMAIN_HOST=gitea.tudominio.com
DB_PASSWORD='tu_password_generado'

📋 Despliegue con Nginx Proxy Manager

services:
  gitea:
    container_name: gitea
    image: gitea/gitea:latest
    restart: unless-stopped
    environment:
      USER_UID: 1000
      USER_GID: 1000
      GITEA__database__DB_TYPE: postgres
      GITEA__database__HOST: gitea-db:5432
      GITEA__database__NAME: ${DB_NAME:-gitea}
      GITEA__database__USER: ${DB_USER:-gitea}
      GITEA__database__PASSWD: ${DB_PASSWORD}
      TZ: Europe/Madrid
    volumes:
      - gitea_data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    networks:
      - proxy
      - gitea-internal
    depends_on:
      - gitea-db

  gitea-db:
    container_name: gitea-db
    image: postgres:18-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${DB_NAME:-gitea}
      POSTGRES_USER: ${DB_USER:-gitea}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - gitea_db:/var/lib/postgresql/data
    networks:
      - gitea-internal

volumes:
  gitea_data:
    name: gitea_data
  gitea_db:
    name: gitea_db

networks:
  proxy:
    external: true
  gitea-internal:
    name: gitea-internal

Variables de entorno necesarias:

DB_PASSWORD='tu_password_generado'

⚠️ IMPORTANTE: Debes configurar en NPM:

Crea un Proxy Host apuntando a gitea:3000
Configura SSL con Let's Encrypt
Opcionalmente activa WebSocket Support para mejor rendimiento

En Environment variables, añade las variables correspondientes
Haz clic en Deploy the stack

Despliegue con Docker CLI

1. Clonar el repositorio

git clone https://git.ictiberia.com/groales/gitea.git
cd gitea

2. Elegir modo de despliegue

Opción A: Traefik

cp docker-compose.override.traefik.yml.example docker-compose.override.yml
cp .env.example .env
# Editar .env y configurar DOMAIN_HOST y DB_PASSWORD

Opción B: Nginx Proxy Manager

No necesitas archivo override, usa el docker-compose.yml base directamente.

Copiar y configurar .env:

cp .env.example .env
# Editar .env y configurar DB_PASSWORD

3. Iniciar el servicio

docker compose up -d

4. Verificar el despliegue

docker compose logs -f gitea
docker compose logs -f gitea-db

Configuración Inicial

1. Acceder a Gitea

Visita https://gitea.tudominio.com y completa el asistente de instalación inicial.

2. Configuración Recomendada en el Asistente

Configuración de Base de Datos (pre-rellenado):

Tipo: PostgreSQL
Host: gitea-db:5432
Usuario: gitea
Contraseña: (la que configuraste en DB_PASSWORD)
Nombre: gitea

Configuración General:

Título del sitio: Nombre de tu instalación
URL Base: https://gitea.tudominio.com
Ruta de repositorios Git: /data/git/repositories (default)
Ruta raíz LFS: /data/git/lfs (default)

Configuración de Administrador:

Nombre de usuario: Tu usuario admin
Contraseña: Contraseña fuerte y segura
Email: Tu email

⚠️ Importante:

Verifica que la URL base sea correcta (con HTTPS)
El primer usuario creado será automáticamente administrador

3. Configuración Post-Instalación

Accede como administrador y configura:

En Site Administration → Configuration:

Deshabilitar auto-registro si no lo necesitas
Configurar SMTP para notificaciones por email
Configurar límites de tamaño de repositorios si lo deseas

Configuración de Email (SMTP)

Para notificaciones y recuperación de contraseñas, edita el archivo de configuración:

# Acceder al contenedor
docker compose exec gitea bash

# Editar app.ini
vi /data/gitea/conf/app.ini

Añade la sección SMTP:

[mailer]
ENABLED = true
FROM = gitea@tudominio.com
PROTOCOL = smtp
SMTP_ADDR = smtp.tudominio.com
SMTP_PORT = 587
USER = gitea@tudominio.com
PASSWD = tu_password_smtp

Reinicia Gitea:

docker compose restart gitea

Uso Básico

Crear un Repositorio

Inicia sesión en Gitea
Haz clic en el + en la esquina superior derecha
Selecciona New Repository
Configura nombre, descripción, visibilidad
Haz clic en Create Repository

Clonar un Repositorio

# Con HTTPS
git clone https://gitea.tudominio.com/usuario/repo.git

# Con SSH (requiere configurar clave SSH en Gitea)
git clone git@gitea.tudominio.com:usuario/repo.git

Configurar SSH

Genera una clave SSH (si no tienes):

ssh-keygen -t ed25519 -C "tu_email@ejemplo.com"

Copia la clave pública:
```
cat ~/.ssh/id_ed25519.pub
```
En Gitea: Settings → SSH / GPG Keys → Add Key

Backup y Restauración

Backup Manual

# Detener Gitea (mantener DB corriendo)
docker compose stop gitea

# Backup de datos de Gitea
docker run --rm -v gitea_data:/data -v $(pwd):/backup alpine \
  tar czf /backup/gitea-data-$(date +%Y%m%d).tar.gz -C /data .

# Backup de PostgreSQL
docker compose exec gitea-db pg_dump -U gitea gitea > gitea-db-$(date +%Y%m%d).sql

# Reiniciar Gitea
docker compose start gitea

Restauración

# Detener servicios
docker compose down

# Restaurar datos de Gitea
docker run --rm -v gitea_data:/data -v $(pwd):/backup alpine \
  sh -c "cd /data && tar xzf /backup/gitea-data-20240101.tar.gz"

# Iniciar solo la DB
docker compose up -d gitea-db

# Esperar a que PostgreSQL esté listo
sleep 10

# Restaurar DB
docker compose exec -T gitea-db psql -U gitea gitea < gitea-db-20240101.sql

# Iniciar todo
docker compose up -d

Backup Automático

Considera usar:

docker-volume-backup
Cron job con el script de backup manual
Duplicati para backups regulares

⚠️ CRÍTICO: Un servidor Git requiere backups regulares y probados.

Actualización

Desde Portainer (Git Repository)

Ve a tu stack gitea
Haz clic en Pull and redeploy

Desde CLI

docker compose pull
docker compose up -d

⚠️ Nota: Gitea puede requerir ejecutar migraciones automáticamente al actualizar.

Solución de Problemas

Gitea no puede conectar a PostgreSQL

Síntomas: Error de conexión a base de datos en el asistente

Soluciones:

# Verificar que ambos contenedores están corriendo
docker compose ps

# Verificar logs de PostgreSQL
docker compose logs gitea-db

# Verificar que están en la misma red
docker network inspect gitea-internal

# Verificar variable DB_PASSWORD
docker compose exec gitea env | grep GITEA__database__PASSWD

Error en instalación inicial

Síntomas: El asistente falla al guardar configuración

Soluciones:

Verifica permisos del volumen gitea_data
Asegúrate de que USER_UID/USER_GID son correctos (1000 por defecto)
Revisa logs: docker compose logs gitea

No puedo hacer push/pull via HTTPS

Síntomas: Error de autenticación o SSL

Soluciones:

Verifica que la URL base en Gitea es correcta (https://gitea.tudominio.com)
Comprueba que el certificado SSL es válido
Asegúrate de usar credenciales correctas
Para NPM: verifica que WebSocket Support está activado

Problemas de rendimiento

Síntomas: Git lento, interfaz web lenta

Soluciones:

Verifica recursos del servidor (CPU, RAM, disco)
PostgreSQL puede necesitar tuning para muchos repos
Considera migrar a SSD si usas HDD
Revisa logs: docker compose logs

Ver logs detallados

# Logs de Gitea
docker compose logs -f gitea

# Logs de PostgreSQL
docker compose logs -f gitea-db

# Logs dentro del contenedor
docker compose exec gitea cat /data/gitea/log/gitea.log

Reiniciar completamente

# Cuidado: esto eliminará TODOS tus datos
docker compose down -v
docker compose up -d

Recursos Adicionales

Seguridad

⚠️ Nunca compartas tu DB_PASSWORD
⚠️ Usa contraseñas fuertes para usuarios administradores
⚠️ Deshabilita auto-registro si es una instalación privada
⚠️ Realiza backups regulares y pruébalos
⚠️ Mantén actualizado Gitea y PostgreSQL
⚠️ Usa HTTPS en producción (obligatorio)
⚠️ Configura SSH keys en lugar de contraseñas para git operations

Licencia

Este repositorio de configuración está bajo licencia MIT. Gitea es software libre bajo licencia MIT.