Gitea Docker Compose: Descubre Tu Propio Servidor Git 2025

Gitea Docker Compose es la solución definitiva para desarrolladores y equipos que necesitan su propio servidor Git privado y autohospedado. En esta guía completa, aprenderás a desplegar Gitea de manera profesional con Docker Compose, configurar repositorios privados ilimitados, y gestionar tu código fuente sin depender de servicios externos. Todo esto con mínimos recursos y máxima eficiencia.

¿Qué es Gitea?

Gitea es un servicio de alojamiento Git autohospedado, ligero y de código abierto escrito en Go. Con más de 52.000 estrellas en GitHub, se ha convertido en la alternativa preferida para quienes buscan control total sobre sus repositorios sin la complejidad de GitLab ni las limitaciones de servicios en la nube.

Esta plataforma ofrece una experiencia similar a GitHub, pero con la libertad de ejecutarla en tu propia infraestructura. Originalmente basada en Gogs, Gitea ha evolucionado hasta convertirse en un proyecto independiente con una comunidad activa y actualizaciones constantes.

Características principales de Gitea

• Repositorios Git ilimitados: Públicos y privados sin restricciones de cantidad
• Pull Requests y Code Review: Sistema completo de revisión de código
• Gitea Actions: CI/CD compatible con GitHub Actions
• Issue Tracking: Gestión de issues con milestones y asignaciones
• Package Registry: Soporte para más de 20 formatos (npm, Docker, Maven, PyPI)
• Autenticación flexible: LDAP, OAuth2, OpenID Connect
• API REST completa: Integración con herramientas externas
• Interfaz multiidioma: Disponible en más de 30 idiomas

Casos de uso ideales

• Desarrollo privado: Equipos que necesitan repositorios privados sin costos mensuales
• Homelab y self-hosting: Entusiastas que gestionan proyectos personales
• Pequeñas empresas: Startups que buscan reducir dependencias de terceros
• Educación: Instituciones que requieren plataformas Git locales para estudiantes
• Proyectos de código abierto: Comunidades que prefieren control total sobre su infraestructura

Gitea Docker Compose vs GitHub vs GitLab

Entender las diferencias entre estas plataformas te ayudará a tomar la mejor decisión para tu proyecto:

Conclusión: Gitea Docker Compose destaca por su ligereza y simplicidad, siendo hasta 10 veces más eficiente que GitLab en consumo de recursos. Ideal para homelabs y pequeños equipos que necesitan funcionalidad completa sin complejidad innecesaria.

Requisitos Previos para Instalar Gitea Docker Compose

Antes de comenzar la instalación, asegúrate de cumplir con estos requisitos mínimos:

Hardware mínimo

• CPU: 2 núcleos (recomendado 4 núcleos para proyectos grandes)
• RAM: 1GB mínimo (2GB recomendado)
• Almacenamiento: 10GB disponibles (SSD recomendado para mejor rendimiento)

Software necesario

• Docker: Versión 20.10 o superior
• Docker Compose: Versión 2.0 o superior
• Sistema operativo: Linux (Ubuntu 22.04/24.04, Debian 11/12), macOS o Windows con WSL2
• Git: Versión 2.0 o superior instalado en el host

Verificar instalación de Docker

# Verificar Docker
docker --version
# Output esperado: Docker version 24.0.0 o superior

# Verificar Docker Compose
docker compose version
# Output esperado: Docker Compose version 2.20.0 o superior

Si no tienes Docker instalado, consulta la documentación oficial de Docker para tu sistema operativo.

Arquitectura de Gitea Docker Compose

Comprender la arquitectura te permitirá personalizar y optimizar tu instalación según tus necesidades específicas.

Componentes principales

Nuestra configuración de Gitea Docker Compose incluye estos servicios esenciales:

• Gitea Server: Aplicación principal escrita en Go
• PostgreSQL: Base de datos relacional para almacenar metadatos (alternativa: MySQL/MariaDB/SQLite)
• Redis (opcional): Caché para mejorar rendimiento en instalaciones grandes
• Volúmenes persistentes: Almacenamiento de repositorios, configuración y base de datos

Flujo de datos

Usuario → Puerto 3000 (HTTP) → Gitea Server
Usuario → Puerto 2222 (SSH) → Gitea Server
Gitea Server → PostgreSQL (Puerto 5432) → Datos persistentes
Gitea Server → Volumen /data → Repositorios Git

Esta arquitectura aísla cada componente en su propio contenedor, facilitando actualizaciones y troubleshooting sin afectar otros servicios.

Instalar Gitea Docker Compose Paso a Paso

Sigue estos pasos para tener tu servidor Git funcionando en menos de 10 minutos.

Paso 1: Crear estructura de directorios

# Crear directorio principal
mkdir -p ~/gitea && cd ~/gitea

# Crear directorios para datos persistentes
mkdir -p gitea-data postgres-data

# Verificar permisos
ls -la

Paso 2: Crear archivo docker-compose.yml

Crea el archivo de configuración principal con este contenido optimizado:

version: "3.8"

networks:
  gitea-network:
    driver: bridge

services:
  gitea-db:
    image: postgres:16-alpine
    container_name: gitea-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: gitea
      POSTGRES_PASSWORD: gitea_secure_password_change_me
      POSTGRES_DB: gitea
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    networks:
      - gitea-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U gitea"]
      interval: 10s
      timeout: 5s
      retries: 5

  gitea-server:
    image: gitea/gitea:latest
    container_name: gitea-app
    restart: unless-stopped
    depends_on:
      gitea-db:
        condition: service_healthy
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=gitea-db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=gitea_secure_password_change_me
    volumes:
      - ./gitea-data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "2222:22"
    networks:
      - gitea-network
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Paso 3: Personalizar variables de entorno

IMPORTANTE: Modifica estos valores antes de iniciar los contenedores:

• POSTGRES_PASSWORD: Usa una contraseña segura (mínimo 16 caracteres)
• USER_UID y USER_GID: Ejecuta id en tu terminal para obtener tus IDs correctos
• GITEA__database__PASSWD: Debe coincidir con POSTGRES_PASSWORD

# Obtener tu UID y GID
id

# Output ejemplo:
# uid=1000(usuario) gid=1000(usuario) groups=1000(usuario),27(sudo),999(docker)

Paso 4: Iniciar Gitea Docker Compose

# Iniciar servicios en segundo plano
docker compose up -d

# Verificar estado de contenedores
docker compose ps

# Ver logs en tiempo real
docker compose logs -f gitea-server

Deberías ver salida similar a esta:

✔ Network gitea_gitea-network      Created
✔ Container gitea-postgres         Started (healthy)
✔ Container gitea-app              Started

NAME              IMAGE                    STATUS         PORTS
gitea-postgres    postgres:16-alpine       Up (healthy)   5432/tcp
gitea-app         gitea/gitea:latest       Up (healthy)   0.0.0.0:2222->22/tcp, 0.0.0.0:3000->3000/tcp

Paso 5: Completar instalación inicial

Abre tu navegador y accede a http://TU_IP_SERVIDOR:3000. Verás el asistente de configuración inicial.

Configuración recomendada:

• Tipo de base de datos: PostgreSQL (ya configurado automáticamente)
• Título del sitio: Tu nombre o empresa
• URL base del servidor: http://tu-dominio.com:3000 o tu IP
• Puerto SSH: 2222 (evita conflicto con SSH del sistema)
• Configuración de email: Configura SMTP si deseas notificaciones por correo
• Cuenta de administrador: Crea tu usuario principal con contraseña fuerte

Haz clic en «Instalar Gitea» y espera 30 segundos. El sistema creará la estructura de base de datos y te redirigirá al dashboard principal.

Configurar Gitea Docker Compose con Proxy Reverso y SSL

Para acceder a tu instalación mediante HTTPS con un dominio personalizado, integraremos Nginx Proxy Manager o Caddy.

Opción A: Nginx Proxy Manager

Si ya tienes Nginx Proxy Manager instalado, agrega un Proxy Host:

• Domain Names: git.tudominio.com
• Scheme: http
• Forward Hostname/IP: gitea-app (nombre del contenedor)
• Forward Port: 3000
• SSL: Solicitar certificado Let’s Encrypt

Opción B: Caddy como proxy reverso

Agrega este servicio a tu docker-compose.yml:

  caddy:
    image: caddy:latest
    container_name: gitea-caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./caddy-data:/data
      - ./caddy-config:/config
    networks:
      - gitea-network

Crea el archivo Caddyfile:

git.tudominio.com {
    reverse_proxy gitea-server:3000
    encode gzip
}

Caddy obtendrá automáticamente certificados SSL de Let’s Encrypt. Reinicia los servicios con docker compose up -d.

Actualizar configuración de Gitea

Edita el archivo de configuración para reflejar tu nueva URL:

# Editar configuración
nano ./gitea-data/gitea/conf/app.ini

# Modificar estas líneas:
[server]
DOMAIN           = git.tudominio.com
ROOT_URL         = https://git.tudominio.com/
HTTP_PORT        = 3000

# Reiniciar Gitea
docker compose restart gitea-server

Gestión Avanzada con Gitea Docker Compose

Optimiza tu instalación con estas configuraciones profesionales que mejorarán rendimiento y seguridad.

Configurar autenticación de dos factores (2FA)

Desde el dashboard de Gitea:

1. Click en tu avatar → Configuración
2. Pestaña «Seguridad»
3. Sección «Autenticación de dos factores»
4. Escanea el código QR con Google Authenticator o Authy
5. Introduce el código de 6 dígitos para activar

Habilitar Gitea Actions (CI/CD)

Gitea Actions es compatible con workflows de GitHub Actions. Para habilitarlo:

# Editar app.ini
nano ./gitea-data/gitea/conf/app.ini

# Agregar sección
[actions]
ENABLED = true

# Reiniciar
docker compose restart gitea-server

Necesitarás registrar un runner para ejecutar los workflows. Consulta la documentación oficial de Gitea Actions.

Configurar límites de recursos

Evita que Gitea consuma todos los recursos del servidor:

services:
  gitea-server:
    # ... configuración existente ...
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 512M

Activar registro de paquetes (Package Registry)

Gitea soporta múltiples formatos de paquetes. Para activar npm, Docker, PyPI, etc.:

# En app.ini
[packages]
ENABLED = true

# Reiniciar servicio
docker compose restart gitea-server

Ahora podrás publicar paquetes npm con npm publish --registry https://git.tudominio.com/api/packages/{owner}/npm/.

Optimización y Best Practices de Gitea Docker Compose

Implementa estas mejores prácticas para maximizar seguridad, rendimiento y fiabilidad de tu servidor Git.

Seguridad

• Contraseñas robustas: Usa generadores como openssl rand -base64 32
• Firewall: Bloquea puertos innecesarios con ufw allow 3000/tcp y ufw allow 2222/tcp
• Actualizaciones: Ejecuta docker compose pull && docker compose up -d mensualmente
• Backups automáticos: Implementa rotación de backups diarios
• Rate limiting: Configura límites de API en app.ini para prevenir abusos

Rendimiento

# En app.ini - Optimizaciones de caché
[cache]
ADAPTER = redis
HOST = redis://gitea-redis:6379/0

[session]
PROVIDER = redis
PROVIDER_CONFIG = redis://gitea-redis:6379/1

Agrega Redis a tu docker-compose.yml si manejas más de 10 usuarios activos:

  gitea-redis:
    image: redis:7-alpine
    container_name: gitea-redis
    restart: unless-stopped
    networks:
      - gitea-network

Backups automatizados

Crea este script en ~/gitea/backup.sh:

#!/bin/bash
BACKUP_DIR="/backups/gitea"
DATE=$(date +%Y%m%d_%H%M%S)

# Crear directorio de backups
mkdir -p $BACKUP_DIR

# Backup de datos de Gitea
docker exec gitea-app /bin/sh -c "/usr/local/bin/gitea dump -c /data/gitea/conf/app.ini -f /tmp/gitea-dump-$DATE.zip"
docker cp gitea-app:/tmp/gitea-dump-$DATE.zip $BACKUP_DIR/

# Backup de PostgreSQL
docker exec gitea-postgres pg_dump -U gitea gitea | gzip > $BACKUP_DIR/postgres-$DATE.sql.gz

# Limpiar backups antiguos (mantener últimos 7 días)
find $BACKUP_DIR -type f -mtime +7 -delete

echo "Backup completado: $DATE"

# Dar permisos de ejecución
chmod +x backup.sh

# Agregar a crontab (backup diario a las 2 AM)
crontab -e
# Agregar: 0 2 * * * /home/usuario/gitea/backup.sh >> /var/log/gitea-backup.log 2>&1

Monitorización

Integra Gitea con herramientas de monitoreo como Uptime Kuma o Prometheus:

# En app.ini - Habilitar métricas
[metrics]
ENABLED = true
TOKEN = tu_token_seguro_aqui

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

Troubleshooting Gitea Docker Compose

Soluciones a los problemas más comunes que encontrarás durante la instalación y operación.

Error: «Database connection failed»

Causa: PostgreSQL no está listo cuando Gitea intenta conectarse.

Solución:

# Verificar estado de PostgreSQL
docker compose logs gitea-db

# Asegurarse de que healthcheck esté funcionando
docker inspect gitea-postgres | grep -A 5 Health

# Reiniciar servicios en orden
docker compose down
docker compose up -d gitea-db
sleep 10
docker compose up -d gitea-server

Error de permisos en volúmenes

Síntoma: Logs muestran «Permission denied» al escribir en /data.

Solución:

# Verificar ownership de directorios
ls -la ~/gitea/

# Corregir permisos (reemplaza 1000 con tu UID)
sudo chown -R 1000:1000 ~/gitea/gitea-data
sudo chmod -R 755 ~/gitea/gitea-data

# Reiniciar contenedor
docker compose restart gitea-server

SSH no funciona (puerto 2222)

Solución:

# Verificar que el puerto esté abierto
sudo ss -tulpn | grep 2222

# Configurar SSH URL correcta en app.ini
nano ./gitea-data/gitea/conf/app.ini

[server]
SSH_DOMAIN = git.tudominio.com
SSH_PORT = 2222

# Agregar clave SSH en tu perfil de Gitea
cat ~/.ssh/id_rsa.pub
# Copiar y pegar en Gitea → Configuración → Claves SSH

Contenedor se reinicia constantemente

Diagnóstico:

# Ver logs detallados
docker compose logs --tail=100 gitea-server

# Verificar recursos disponibles
docker stats

# Comprobar configuración
docker compose config

Si ves errores de memoria, aumenta los límites en docker-compose.yml o libera recursos del host.

Migrar repositorios desde GitHub

Gitea facilita la migración directa:

1. En Gitea: Click en «+» → «Nueva migración»
2. Seleccionar «GitHub»
3. Introducir URL del repositorio: https://github.com/usuario/repo
4. Opcional: Agregar token de acceso de GitHub para repositorios privados
5. Click en «Migrar repositorio»

Gitea importará issues, pull requests, releases y wiki automáticamente.

Conclusión

Has aprendido a desplegar y configurar Gitea Docker Compose de manera profesional, desde la instalación básica hasta optimizaciones avanzadas con SSL, backups automatizados y CI/CD. Esta solución te proporciona control total sobre tu código fuente sin depender de servicios externos, con un consumo de recursos mínimo y funcionalidad empresarial.

Con Gitea, obtienes repositorios ilimitados, package registry para múltiples formatos, y compatibilidad con GitHub Actions, todo ejecutándose con apenas 200MB de RAM. Ideal para equipos de desarrollo, entusiastas del self-hosting, y proyectos educativos que valoran privacidad y autonomía.

Próximos pasos recomendados:

• Configura Gitea Actions para automatizar tus despliegues
• Implementa webhooks para integrar con servicios externos
• Explora el package registry para alojar paquetes npm, Docker o PyPI
• Integra autenticación LDAP o OAuth2 si trabajas en equipo
• Documenta tus repositorios con wikis integradas

Si buscas más soluciones de automatización y monitoreo, consulta nuestra guía sobre Docker Compose para self-hosting.

FAQ: Preguntas Frecuentes sobre Gitea Docker Compose

¿Cuántos recursos necesita Gitea Docker Compose?

Gitea es extremadamente ligero. Para un equipo pequeño (hasta 10 usuarios), necesitas mínimo 2 CPU cores y 1GB de RAM. En producción con PostgreSQL y Redis, consume aproximadamente 300-400MB de RAM en reposo. Esto es 5-10 veces menos que GitLab, que requiere al menos 8GB de RAM para funcionar correctamente.

¿Puedo usar MySQL en lugar de PostgreSQL con Gitea Docker Compose?

Sí, Gitea soporta PostgreSQL, MySQL, MariaDB, SQLite y MSSQL. Para cambiar a MySQL, modifica el servicio de base de datos en docker-compose.yml y ajusta las variables de entorno GITEA__database__DB_TYPE=mysql. PostgreSQL es recomendado por su mejor rendimiento con repositorios grandes y soporte completo de características como full-text search.

¿Cómo actualizo Gitea Docker Compose a la última versión?

Actualizar es simple y seguro con Docker Compose:

# Hacer backup antes de actualizar
./backup.sh

# Descargar nueva imagen
docker compose pull gitea-server

# Recrear contenedor con nueva versión
docker compose up -d gitea-server

# Verificar logs
docker compose logs -f gitea-server

Gitea maneja migraciones de base de datos automáticamente al iniciar. Siempre haz backups antes de actualizar versiones mayores.

¿Es seguro exponer Gitea Docker Compose a internet?

Sí, siempre que implementes estas medidas de seguridad: (1) SSL/TLS obligatorio con certificados válidos, (2) autenticación de dos factores para administradores, (3) firewall configurado para permitir solo puertos necesarios, (4) actualizaciones mensuales, (5) backups automáticos diarios, y (6) rate limiting activado en la configuración. Gitea tiene un buen historial de seguridad con actualizaciones rápidas para cualquier vulnerabilidad reportada.

¿Gitea Docker Compose soporta Git LFS (Large File Storage)?

Sí, Git LFS está habilitado por defecto en Gitea. Los archivos grandes se almacenan en el volumen /data/lfs dentro del contenedor. Puedes configurar almacenamiento externo como MinIO o AWS S3 editando la sección [lfs] en app.ini. Esto es útil para proyectos con assets grandes como juegos, diseño gráfico o machine learning con datasets pesados.

Recursos Adicionales

• Documentación oficial de Gitea
• Repositorio oficial en GitHub
• Documentación de Docker Compose
• Guía oficial de instalación con Docker
• Blog oficial de Gitea