Cómo autoalojar Gitea en un VPS con Docker (2026)

Todos los equipos llegan a ese momento. Una plataforma cambia sus precios, restringe los repositorios privados o simplemente se vuelve más una carga que un activo. Montar tu propio servidor Git solía significar semanas de configuración y una persona de ops dedicada a mantenerlo. Con Docker y un VPS de buen precio, ahora significa una tarde.

Autoalojar tu servidor Git en un VPS te da control total de tu código, sin cobro por usuario y sin acceso de terceros a tus repositorios. Para un desarrollador solo o un equipo pequeño, esa combinación es difícil de superar. Gitea lo vuelve práctico: es una plataforma de hosting de Git completa que corre sin problemas en hardware modesto, cubre todo el flujo de code review y pasa de cero a HTTPS en menos de una hora.

¿Qué es Gitea?

Gitea es un servicio Git autoalojado y de código abierto, escrito en Go. El proyecto nació en 2016 como un fork de Gogs y creció hasta convertirse en una plataforma con todas las funciones: repositorios, pull requests, issues, wikis, webhooks y un package registry integrado. La interfaz web se parece tanto a GitHub que los desarrolladores que buscan una alternativa autoalojada a GitHub la encuentran familiar desde el primer día.

El runtime de Go mantiene el binario pequeño y el uso de memoria bajo. Los requisitos del sistema indican que 1 GB de RAM suele bastar para equipos y proyectos pequeños. Eso es lo que la hace apta para un VPS pequeño en lugar de una máquina dedicada.

Forgejo es un fork comunitario de Gitea con mantenimiento activo, creado en 2022 cuando surgieron dudas sobre la gobernanza del proyecto. Ambos comparten la misma base de código y la misma estructura de imagen Docker, así que el setup que describe esta guía aplica para los dos. Si todavía no te decides, las FAQ del final cubren las diferencias con más detalle.

¿Por qué autoalojar Gitea en un VPS?

Las razones principales por las que los desarrolladores autoalojan Gitea no han cambiado, pero salen a la conversación con más frecuencia ahora que la mayoría de las plataformas con hosting pasaron al cobro por usuario:

• Propiedad del código. Los repositorios viven en tu servidor. Ningún proveedor puede borrar tu cuenta, restringir tus repositorios privados ni cambiarte el modelo de precios sin avisar.
• Sin costo por usuario. Tengas 3 usuarios o 30, la cuenta mensual es la misma: lo que cueste tu VPS. Por unos pocos euros al mes con un VPS de entrada de Contabo, las cuentas favorecen rápido al autoalojamiento en cuanto tienes más de dos o tres colaboradores activos.
• Ligero por diseño. Gitea corre en hardware con el que plataformas más pesadas batallarían. Un VPS pequeño aguanta el trabajo diario de push y pull de un equipo real sin esfuerzo.
• Residencia de datos. Si tu equipo o tus clientes exigen que el código se quede dentro de la UE, Contabo cumple ese requisito sin sobreprecio. No hay un «nivel compatible con el RGPD» aparte por el que tengas que pagar.

Requisitos previos

Antes de empezar, confirma que tienes lo siguiente para un setup de Gitea con Docker:

• Un VPS con Ubuntu 22.04 o 24.04 – un VPS de entrada de Contabo basta para la mayoría de los equipos
• Docker y Docker Compose instalados – sigue nuestra guía de instalación de Docker para Ubuntu o usa el complemento de Docker para tu VPS en Contabo
• Un dominio o subdominio con un registro A apuntando a la dirección IP de tu VPS (necesario para el HTTPS del Paso 4)
• Acceso SSH como root o con sudo al servidor

Paso 1: Prepara el VPS e instala Docker

1. Contrata un VPS desde la página de VPS de Contabo. Crea una contraseña segura y guárdala en un lugar seguro. Encuentras tu dirección IP y más información en tu correo «Your login data!», que recibes después de hacer el pedido.

2. Conéctate por SSH:

ssh root@YOUR_SERVER_IP

3. Actualiza todos los paquetes antes de hacer cualquier otra cosa:

apt update && apt upgrade -y

4. Asegúrate de tener Docker instalado para el setup de Gitea con Docker. En Contabo, basta con elegir el complemento de Docker al momento del checkout, que entrega el VPS con Docker ya instalado y configurado. Ambos caminos producen al final el mismo Docker Engine funcionando, solo que con distinto esfuerzo y tiempo. Verifica las versiones:

docker --version
docker compose version
sudo systemctl status docker

5. Crea un directorio dedicado para el stack de Gitea:

mkdir -p /opt/gitea && cd /opt/gitea

Mantén la instalación en /opt/gitea para que los volúmenes, los archivos compose y cualquier cambio de configuración futuro queden en un mismo lugar.

Paso 2: docker-compose.yml de Gitea con PostgreSQL

SQLite funciona para setups muy pequeños, pero PostgreSQL es la opción correcta para cualquier cosa que use un equipo. Maneja las escrituras concurrentes de forma limpia y hace que los backups sean directos.

Antes de ejecutar el comando de abajo, reemplaza dos valores:

• Las dos apariciones de changeme por una contraseña real
• Las dos apariciones de git.yourdomain.com por tu dominio real

Luego pega todo el bloque en la terminal de tu servidor de una sola vez para la instalación de Gitea:

cat > /opt/gitea/docker-compose.yml << 'EOF'
services:
  db:
    image: postgres:16
    restart: always
    environment:
      POSTGRES_USER: gitea
      POSTGRES_PASSWORD: changeme
      POSTGRES_DB: gitea
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - gitea_net

  gitea:
    image: gitea/gitea:latest
    restart: always
    depends_on:
      - db
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=changeme
      - GITEA__server__ROOT_URL=https://git.yourdomain.com
      - GITEA__server__SSH_DOMAIN=git.yourdomain.com
      - GITEA__server__SSH_PORT=222
    ports:
      - "127.0.0.1:3000:3000"
      - "222:22"
    volumes:
      - gitea_data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    networks:
      - gitea_net

networks:
  gitea_net:

volumes:
  postgres_data:
  gitea_data:
EOF

El comando crea el archivo en silencio y te devuelve al prompt sin ningún mensaje de confirmación: eso es normal. Verifica que el archivo se escribió correctamente:

cat /opt/gitea/docker-compose.yml

La salida debe mostrar el YAML completo con tu contraseña y tu dominio en su lugar. Cuando lo haga, pasa al Paso 3 de tu setup de Gitea.

Paso 3: Configuración inicial y cuenta de administrador

1. Levanta el stack en modo detached:

docker compose up -d

2. Espera unos 10 segundos y confirma que ambos contenedores están corriendo:

docker compose ps

Tanto db como gitea deben mostrar el estado «running». Si gitea se está reiniciando, revisa los logs con docker compose logs gitea: un error de conexión a la base de datos en este punto casi siempre significa que las dos contraseñas changeme de tu archivo Compose no coinciden.

3. Abre http://YOUR_SERVER_IP:3000 en tu navegador. El asistente de configuración de Gitea carga en la primera visita.

• Antes de abrir el asistente, actualiza temporalmente ROOT_URL en tu docker-compose.yml a la IP de tu servidor:
  – GITEA__server__ROOT_URL=http://YOUR_SERVER_IP:3000
• Reinicia el contenedor y abre el asistente. Esto lo cambiarás a tu dominio real en el Paso 4, una vez que nginx esté en su lugar.

4. Los campos de la base de datos ya deberían reflejar tu archivo Compose. Baja hasta la sección «Administrator Account Settings» al final y define un nombre de usuario, una dirección de correo y una contraseña para el primer usuario administrador.

5. Haz clic en «Install Gitea«. Gitea escribe la configuración, inicializa la base de datos y te redirige a la página de inicio de sesión.

6. Inicia sesión con el nombre de usuario tal como lo escribiste: Gitea distingue mayúsculas de minúsculas, así que Admin y admin son distintos. En el primer inicio de sesión, Gitea te pedirá que actualices tu contraseña. Hazlo y aterrizarás en el dashboard.

Una vez en el dashboard, regresa el binding de puerto en tu docker-compose.yml a 127.0.0.1:3000:3000 y reinicia el contenedor antes de pasar al Paso 4:

docker compose up -d gitea

Esto cierra el acceso directo al puerto 3000 y prepara a Gitea para correr detrás de nginx.

Paso 4: Agrega un proxy inverso y HTTPS

Con Gitea corriendo, el siguiente paso es montar un proxy inverso para Gitea con nginx y un certificado TLS de Let’s Encrypt. Esto te da una dirección https:// en forma y cierra el acceso directo al puerto 3000.

Necesitas un dominio o subdominio apuntando a la IP de tu servidor antes de continuar. Si justo necesitas un dominio nuevo, aquí tienes un tutorial paso a paso para obtener un dominio en Contabo.

Instala nginx y Certbot:

apt install nginx certbot python3-certbot-nginx -y

Obtén un certificado TLS:

certbot --nginx -d your.domain.com

Certbot te pedirá una dirección de correo y te pedirá aceptar los Términos de Servicio. Si te pregunta por la redirección de HTTP a HTTPS, elige la opción 2. Si todo sale bien, verás las rutas del certificado confirmadas en la salida.

Crea la configuración de nginx para Gitea:

cat > /etc/nginx/sites-available/gitea << 'EOF'
server {
    listen 80;
    server_name your.domain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name your.domain.com;

    ssl_certificate /etc/letsencrypt/live/your.domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your.domain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    client_max_body_size 512M;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
EOF

Actívala, elimina el sitio default y recarga nginx:

ln -s /etc/nginx/sites-available/gitea /etc/nginx/sites-enabled/
rm /etc/nginx/sites-enabled/default
nginx -t && systemctl reload nginx

Actualiza Gitea para que use tu dominio:

Abre tu docker-compose.yml y cambia estas dos líneas a tu dominio real:

- GITEA__server__ROOT_URL=https://your.domain.com
- GITEA__server__SSH_DOMAIN=your.domain.com

Al mismo tiempo, regresa el binding de puerto a solo localhost:

- "127.0.0.1:3000:3000"

Luego reinicia Gitea:

docker compose up -d gitea

Abre https://your.domain.com en tu navegador. Deberías ver la interfaz de Gitea servida sobre HTTPS con un candado válido.

Paso 5: Configura SSH para las operaciones de Git

Prueba la conexión SSH de Gitea desde tu máquina local:

ssh -p 222 -T [email protected]

En la primera conexión verás una pregunta sobre la autenticidad del host: escribe yes para continuar. La respuesta esperada es Permission denied (publickey). Eso confirma que SSH funciona; el error solo significa que todavía no has agregado una clave.

Para agregar tu clave pública SSH, inicia sesión en Gitea y ve a «User Settings > SSH / GPG Keys«. Pega tu clave pública y guarda. Una vez agregada, clona un repositorio con:

git clone ssh://[email protected]:222/username/repo.git

Gitea genera la URL de clonado correcta de forma automática en la interfaz del repositorio: cópiala de ahí en lugar de armarla a mano.

Siguientes pasos: asegura y respalda tu servidor Gitea

Una instancia de Gitea funcionando no es una lista para producción. Dos cosas importan antes de darla por terminada:

Endurece el servidor. Desactiva el inicio de sesión SSH como root, configura fail2ban para los fallos de autenticación repetidos, desactiva el registro público en los ajustes de Gitea si no lo necesitas y restringe el tráfico entrante solo a los puertos 22, 80, 443 y 222 usando el Firewall de Contabo en el Customer Control Panel. Endurecer el servidor se hace en un dos por tres.

Respalda los volúmenes. Tus datos viven en los volúmenes de Docker gitea_data y postgres_data. Detén el stack, empaqueta cada volumen en un archivo local con tar y cópialo fuera del servidor a Contabo Object Storage o a otro destino remoto de forma periódica para tu backup de Gitea.

Ninguna de las dos es opcional si el código o el trabajo de otras personas depende de la instancia.

Solución de problemas

El contenedor de Gitea se reinicia una y otra vez. Ejecuta docker compose logs gitea y busca la primera línea de error. Un error password authentication failed significa que el valor de GITEA__database__PASSWD no coincide con POSTGRES_PASSWORD. Corrige ambos y luego vuelve a ejecutar docker compose up -d.

El inicio de sesión limpia el formulario sin mensaje de error. Esto significa que el inicio de sesión sí funciona, pero Gitea te redirige de vuelta a la página de login. La causa casi siempre es un desajuste en ROOT_URL: Gitea intenta redirigir al dominio configurado, falla y regresa al login. Asegúrate de que ROOT_URL en tu docker-compose.yml coincida con la dirección que realmente usas para acceder a Gitea, y reinicia el contenedor.

Push grande rechazado con un 413. Agrega o aumenta client_max_body_size en el bloque server de nginx y recarga nginx.

El clonado por SSH falla con Connection refused. Confirma que el puerto 222 está abierto en tu firewall. Si usas el Firewall de Contabo del Customer Control Panel, agrega una regla de entrada para el puerto TCP 222.

El puerto 3000 no es alcanzable desde el navegador. Gitea está ligado a 127.0.0.1:3000 por defecto, lo que significa que solo acepta conexiones del propio servidor. Esto es intencional: nginx le pasa las solicitudes. Si necesitas acceder al puerto 3000 directamente para pruebas, cambia temporalmente el binding a 0.0.0.0:3000:3000 en tu docker-compose.yml y reinicia el contenedor. Regrésalo antes de pasar a producción.

¿Por qué correr Gitea en Contabo?

Gitea es una carga de trabajo ligera. Un VPS de entrada tiene recursos de sobra para manejar la actividad diaria de Git de un equipo pequeño o mediano, con margen para la base de datos, nginx y tareas administrativas ocasionales. Si más adelante agregas runners de CI/CD a la misma máquina, subir un plan te da margen cómodo sin un salto de costo importante.

Para equipos con requisitos de residencia de datos, Contabo tiene centros de datos por toda Europa y el mundo. Elige al momento de aprovisionar la región que encaje con tus necesidades de cumplimiento: sin nivel premium y sin trámites.

FAQ: autoalojar Gitea