Instalación y configuración de Forge

1. Qué es Forgejo y por qué es la mejor opción en 2026

Forgejo (pronunciado «for-ye-o») es un fork de Gitea creado por la comunidad en respuesta a la comercialización del proyecto original. En 2026, Forgejo se ha convertido en el estándar de facto para quienes buscan un «punto medio» entre el pesado GitLab y soluciones demasiado ascéticas como SourceHut.

La filosofía principal de Forgejo es "Liberated Software". Esto significa que todas las funciones, incluidos el CI/CD avanzado y el registro de paquetes, están disponibles de forma gratuita y con código abierto. A diferencia de Gitea, donde algunas funciones corporativas pueden estar limitadas o dirigidas a clientes de pago, Forgejo se desarrolla como un proyecto perteneciente a la comunidad.

Ventajas clave para el propietario de un VPS:

• Bajo consumo de recursos: En modo de espera, Forgejo consume menos de 200 MB de memoria RAM.
• Compatibilidad binaria: Si anteriormente usaba Gitea, la transición a Forgejo toma 5 minutos sin pérdida de datos.
• CI/CD integrado: Ya no es necesario configurar integraciones complejas con Jenkins o Drone CI. Forgejo Actions entiende la sintaxis de los archivos YAML de GitHub Actions.
• Herramienta única: El código, los tickets (issues), los tableros Kanban, la wiki y el registro de contenedores se encuentran en una sola interfaz.

2. Comparación de Forgejo con alternativas (GitLab, Gitea, GitHub)

Al elegir una plataforma Git para hospedar en su propio servidor, es importante entender la diferencia en el consumo de recursos y funcionalidades. A continuación se muestra una tabla comparativa de las soluciones actuales para 2026.

GitLab es una herramienta potente y completa, pero su instalación en un VPS económico a menudo provoca bloqueos por falta de memoria. Forgejo, por otro lado, es ideal para desarrolladores individuales y equipos de hasta 50 personas que trabajan con hardware económico.

3. Qué configuración de VPS se necesita para esta tarea

Aunque Forgejo es extremadamente poco exigente, el rendimiento de su hosting Git dependerá directamente de la velocidad del subsistema de disco y de la cantidad de memoria RAM para el almacenamiento en caché de los objetos Git.

Requisitos mínimos (1-3 usuarios, proyectos pequeños):

• CPU: 1 núcleo
• RAM: 1 GB
• Disco: 20 GB SSD/NVMe
• SO: Ubuntu 24.04 LTS o Debian 13

Requisitos recomendados (equipo, CI/CD, Docker Registry):

• CPU: 2-4 núcleos (importante para la compilación rápida de contenedores en CI/CD)
• RAM: 4 GB (permite mantener la BD en caché y que los runners funcionen eficientemente)
• Disco: 50+ GB NVMe (el volumen depende de la cantidad de imágenes Docker almacenadas)
• Red: 1 Gbps (para carga/descarga rápida de repositorios grandes)

Para un funcionamiento estable del sistema, especialmente si planea usar activamente Forgejo Actions para compilar proyectos, lo mejor es un VPS adecuado con recursos dedicados, para que los procesos de compilación no ralenticen la interfaz web.

La ubicación del servidor también es importante: elija un centro de datos con el mínimo ping hacia sus desarrolladores, ya que los protocolos Git (SSH/HTTPS) son sensibles a los retrasos al transferir muchos archivos pequeños.

4. Preparación del servidor: seguridad básica y utilidades del sistema

Antes de instalar Docker, es necesario asegurar el servidor. Configuraremos el firewall, crearemos un usuario independiente e instalaremos protección contra ataques de fuerza bruta.

Actualice la lista de paquetes y el sistema a la versión más reciente:

sudo apt update && sudo apt upgrade -y

Instale las herramientas básicas necesarias:

sudo apt install -y curl wget git vim ufw fail2ban software-properties-common

Configure el firewall UFW. Necesitaremos los puertos 22 (SSH), 80 (HTTP), 443 (HTTPS) y el puerto 2222 para Git a través de SSH (para no entrar en conflicto con el servidor SSH principal del sistema):

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 2222/tcp
sudo ufw enable

La configuración de Fail2Ban ayudará a proteger el SSH contra el descifrado de contraseñas. Cree una configuración local:

sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Cree un usuario del sistema bajo el cual funcionará Forgejo (por seguridad, no se recomienda ejecutar el servicio como root, incluso dentro de un contenedor):

sudo adduser --disabled-password --gecos "" git

5. Instalación de Docker y Docker Compose

En 2026, el uso de Docker es el estándar para servicios auto-hospedados. Esto simplifica la actualización y la migración de Forgejo a otro servidor.

Instale el repositorio oficial de Docker:

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Instale Docker Engine y el plugin Docker Compose:

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Añada el usuario actual al grupo docker para ejecutar comandos sin sudo:

sudo usermod -aG docker $USER

Nota: después de este comando, es necesario volver a iniciar sesión en la terminal.

6. Despliegue de Forgejo: Docker Compose y base de datos

Utilizaremos PostgreSQL como base de datos, ya que es más fiable que SQLite a medida que crece el número de repositorios y el uso activo de CI/CD.

Cree un directorio de trabajo:

mkdir -p ~/forgejo && cd ~/forgejo

Cree un archivo docker-compose.yml con la siguiente configuración:

services:
  server:
    image: codeberg.org/forgejo/forgejo:10
    container_name: forgejo
    restart: always
    environment:
      - USER_UID=1001
      - USER_GID=1001
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=db:5432
      - FORGEJO__database__NAME=forgejo
      - FORGEJO__database__USER=forgejo
      - FORGEJO__database__PASSWD=your_strong_password
    volumes:
      - ./data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "127.0.0.1:3000:3000"
      - "2222:22"
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    restart: always
    environment:
      - POSTGRES_USER=forgejo
      - POSTGRES_PASSWORD=your_strong_password
      - POSTGRES_DB=forgejo
    volumes:
      - ./postgres:/var/lib/postgresql/data

Importante: Reemplace your_strong_password por una contraseña real. Tenga en cuenta que estamos exponiendo la interfaz web de Forgejo en 127.0.0.1:3000. Esto se hace para que no sea accesible directamente desde el exterior, sino solo a través de nuestro Reverse Proxy (Caddy).

Inicie los contenedores:

docker compose up -d

7. Configuración de Reverse Proxy y HTTPS automático mediante Caddy

Caddy es un servidor web moderno que obtiene y renueva automáticamente los certificados SSL de Let's Encrypt. Es mucho más sencillo que configurar Nginx con Certbot.

Instale Caddy:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Edite /etc/caddy/Caddyfile:

git.yourdomain.com {
    reverse_proxy localhost:3000
    
    header {
        # Configuración de seguridad
        Strict-Transport-Security "max-age=31536000;"
        X-Content-Type-Options nosniff
        X-Frame-Options DENY
        Referrer-Policy no-referrer-when-downgrade
    }
}

Reemplace git.yourdomain.com por su dominio real, que debe apuntar a la IP de su VPS (registro A). Reinicie Caddy:

sudo systemctl restart caddy

Ahora puede abrir https://git.yourdomain.com en su navegador y completar la instalación de Forgejo a través de la interfaz web. El primer usuario registrado se convertirá automáticamente en administrador.

8. Configuración de Forgejo Actions: ejecución del Runner de CI/CD

Forgejo Actions es un potente sistema de automatización integrado. Para su funcionamiento se requiere un componente independiente — el Runner, que ejecutará los comandos de compilación.

Primero, habilite el soporte de Actions en Forgejo. Abra el archivo de configuración dentro del contenedor o añada una variable de entorno en docker-compose.yml:

# Añada a la sección environment del servicio server en docker-compose.yml:
- FORGEJO__actions__ENABLED=true

Ahora añadiremos el servicio del runner a nuestro docker-compose.yml:

  runner:
    image: codeberg.org/forgejo/runner:6.0
    container_name: forgejo-runner
    restart: always
    depends_on:
      - server
    volumes:
      - ./runner-data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - FORGEJO_INSTANCE_URL=https://git.yourdomain.com
      - FORGEJO_RUNNER_REGISTRATION_TOKEN=SU_TOKEN_DE_ADMINISTRACION
      - FORGEJO_RUNNER_NAME=vps-runner
      - FORGEJO_RUNNER_LABELS=ubuntu-latest:docker://node:20-bullseye,debian-latest:docker://debian:bookworm

Para obtener el FORGEJO_RUNNER_REGISTRATION_TOKEN, vaya al panel de control de Forgejo: Site Administration -> Actions -> Runners -> Create new Runner.

Inicie el runner:

docker compose up -d runner

Ahora, cualquier repositorio que contenga un archivo .forgejo/workflows/build.yml ejecutará automáticamente la compilación en su VPS.

9. Configuración del Docker Registry integrado

Forgejo permite almacenar imágenes de Docker directamente en el repositorio del proyecto. Esto elimina la necesidad de utilizar Docker Hub o alternativas de pago.

Por defecto, el registro de paquetes está habilitado. Para autenticarse en él desde su máquina local, utilice el comando estándar docker login:

docker login git.yourdomain.com

Utilice su nombre de usuario y contraseña (o un Personal Access Token, que es más seguro). Ejemplo de etiquetado y push de una imagen:

docker tag my-app:latest git.yourdomain.com/username/my-app:latest
docker push git.yourdomain.com/username/my-app:latest

Todas las imágenes se almacenan en la carpeta /data/packages dentro del contenedor de Forgejo, lo que facilita la gestión del espacio en disco.

10. Copias de seguridad y mantenimiento

La falta de copias de seguridad es el principal error en el self-hosting. En Forgejo, es necesario respaldar tres cosas: la base de datos, los archivos de configuración (app.ini) y los propios repositorios.

Cree un script de copia de seguridad sencillo backup.sh:

#!/bin/bash
BACKUP_DIR="/home/user/backups"
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
mkdir -p $BACKUP_DIR

# Copia de seguridad de la base de datos
docker exec forgejo-db-1 pg_dump -U forgejo forgejo > $BACKUP_DIR/db_$TIMESTAMP.sql

# Copia de seguridad de datos de Forgejo (configuraciones y repositorios)
tar -czf $BACKUP_DIR/data_$TIMESTAMP.tar.gz ./data

# Eliminación de copias de seguridad antiguas (más de 7 días)
find $BACKUP_DIR -type f -mtime +7 -delete

Añada la ejecución del script a crontab (crontab -e) para que se ejecute cada noche a las 3:00:

0 3 * * * /bin/bash /home/user/forgejo/backup.sh

Actualización de Forgejo: El proceso de actualización es extremadamente sencillo gracias a Docker. Basta con cambiar la versión de la imagen en docker-compose.yml y ejecutar:

docker compose pull
docker compose up -d

11. Solución de problemas + FAQ

Error: "SSH connection refused" al intentar git push

Compruebe que está utilizando el puerto correcto. Por defecto, SSH en nuestra configuración funciona en el puerto 2222. La URL de su repositorio debería verse así: ssh://[email protected]:2222/user/repo.git. Asegúrese también de que su clave SSH pública haya sido añadida a su perfil de Forgejo.

¿Qué configuración de VPS es el mínimo adecuado para Forgejo?

Para el trabajo cómodo de un solo desarrollador, 1 GB de RAM y 1 núcleo de CPU son suficientes. Sin embargo, si habilita Forgejo Actions (CI/CD), al iniciar una compilación (por ejemplo, en Go o Rust), el consumo de memoria puede dispararse instantáneamente a 2-4 GB. Para tales tareas, es mejor elegir un plan con 4 GB de RAM.

¿Qué elegir: VPS o servidor dedicado para esta tarea?

Para la mayoría de los equipos de hasta 20 personas, un VPS es la elección ideal. Un servidor dedicado solo debe considerarse en dos casos: si el volumen de su código y artefactos (Docker Registry) supera los 1-2 TB, o si necesita un aislamiento absoluto de recursos para procesos pesados de CI/CD que no deben afectar la capacidad de respuesta de la interfaz de Git.

¿Cómo limitar el registro de nuevos usuarios?

Después de crear su cuenta de administrador, vaya a Site Administration -> Configuration y establezca DISABLE_REGISTRATION = true. Esto evitará que personas ajenas creen cuentas en su servidor público.

Forgejo consume demasiado espacio en disco, ¿qué hacer?

Los principales consumidores de espacio suelen ser el Docker Registry y los registros de las compilaciones. Limpie regularmente las imágenes antiguas y configure una política de retención (Retention Policy) en los ajustes de paquetes de Forgejo. Compruebe también la carpeta /data/tmp; a veces pueden acumularse archivos temporales tras importaciones fallidas.

¿Se pueden transferir datos desde GitHub?

Sí, Forgejo cuenta con una herramienta de migración integrada. Permite importar no solo el código, sino también Issues, Pull Requests, Wiki e incluso Milestones. Para ello, basta con indicar la URL del repositorio de GitHub y su Personal Access Token.

12. Conclusiones y siguientes pasos

Hemos desplegado con éxito un entorno de desarrollo profesional en nuestro propio VPS. Ahora tiene el control total sobre su código, imágenes de contenedores y procesos de automatización, sin depender de las políticas de proveedores de la nube externos.

Qué hemos obtenido:

• Hosting Git privado con alto rendimiento.
• SSL automático a través de Caddy.
• Sistema de CI/CD propio, compatible con GitHub Actions.
• Docker Registry para almacenar imágenes privadas.

Hacia dónde dirigirse a continuación:

1. Monitoreo: Configure la exportación de métricas de Forgejo a Prometheus y visualícelas en Grafana para supervisar la carga del servidor.
2. Seguridad: Configure la autenticación de dos factores (2FA) para su cuenta.
3. Almacenamiento externo: Si planea almacenar terabytes de datos, configure el almacenamiento de objetos (LFS y paquetes) en un almacenamiento compatible con S3.

El self-hosting no es solo un ahorro de costes, sino también un paso importante hacia la soberanía digital de su equipo o proyecto. Forgejo proporciona todas las herramientas necesarias para ello, siendo una solución sencilla y fiable.