Instalación de Forgejo: Hosting Git Autoalojado

Forgejo es una plataforma de hosting Git autoalojada, impulsada por la comunidad, que nació como fork de Gitea con el objetivo de mantener una gobernanza abierta y un desarrollo centrado en las necesidades de los usuarios. Ligera, fácil de instalar y compatible con GitHub Actions, Forgejo es una excelente opción para equipos que buscan independencia y control total sobre su infraestructura Git.

Requisitos Previos

  • Servidor Linux (Ubuntu 20.04+, Debian 11+ o CentOS 8+)
  • Mínimo 512 MB de RAM (recomendado 1 GB)
  • Docker y Docker Compose (para instalación con Docker)
  • Dominio configurado apuntando al servidor
  • Acceso root o sudo

Instalación con Docker

Docker es la forma más rápida de poner en marcha Forgejo:

# Crear estructura de directorios
mkdir -p /opt/forgejo/{data,config}
cd /opt/forgejo

# Crear el fichero docker-compose.yml
tee docker-compose.yml << 'EOF'
version: "3.8"

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:7
    container_name: forgejo
    restart: unless-stopped
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - FORGEJO__database__DB_TYPE=sqlite3
    ports:
      - "3000:3000"
      - "2222:22"
    volumes:
      - ./data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro

  # Opcional: usar MySQL en lugar de SQLite
  # db:
  #   image: mysql:8
  #   environment:
  #     MYSQL_ROOT_PASSWORD: contraseña_root
  #     MYSQL_DATABASE: forgejo
  #     MYSQL_USER: forgejo
  #     MYSQL_PASSWORD: contraseña_forgejo
  #   volumes:
  #     - ./mysql:/var/lib/mysql
EOF

# Arrancar Forgejo
docker compose up -d

# Seguir los logs de inicio
docker compose logs -f

Para usar MySQL en lugar de SQLite (recomendado para producción):

# docker-compose.yml con MySQL
tee docker-compose.yml << 'EOF'
version: "3.8"

services:
  db:
    image: mysql:8.0
    container_name: forgejo-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: root_seguro_123
      MYSQL_DATABASE: forgejo
      MYSQL_USER: forgejo
      MYSQL_PASSWORD: forgejo_seguro_456
    volumes:
      - db_data:/var/lib/mysql

  forgejo:
    image: codeberg.org/forgejo/forgejo:7
    container_name: forgejo
    restart: unless-stopped
    depends_on:
      - db
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - FORGEJO__database__DB_TYPE=mysql
      - FORGEJO__database__HOST=db:3306
      - FORGEJO__database__NAME=forgejo
      - FORGEJO__database__USER=forgejo
      - FORGEJO__database__PASSWD=forgejo_seguro_456
    ports:
      - "3000:3000"
      - "2222:22"
    volumes:
      - forgejo_data:/data

volumes:
  db_data:
  forgejo_data:
EOF

docker compose up -d

Instalación Nativa en Linux

Para instalar Forgejo directamente en el sistema sin Docker:

# Crear usuario del sistema
sudo adduser \
  --system \
  --shell /bin/bash \
  --gecos 'Forgejo' \
  --group \
  --disabled-password \
  --home /home/git \
  git

# Descargar el binario de Forgejo
FORGEJO_VERSION="7.0.4"
wget "https://codeberg.org/forgejo/forgejo/releases/download/v${FORGEJO_VERSION}/forgejo-${FORGEJO_VERSION}-linux-amd64" \
  -O /usr/local/bin/forgejo

chmod +x /usr/local/bin/forgejo

# Crear directorios necesarios
sudo mkdir -p /var/lib/forgejo/{custom,data,log}
sudo chown -R git:git /var/lib/forgejo
sudo mkdir -p /etc/forgejo
sudo chown root:git /etc/forgejo
sudo chmod 770 /etc/forgejo

Crea el servicio systemd:

sudo tee /etc/systemd/system/forgejo.service << 'EOF'
[Unit]
Description=Forgejo (Beyond Coding)
After=syslog.target
After=network.target

[Service]
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/forgejo/
ExecStart=/usr/local/bin/forgejo web --config /etc/forgejo/app.ini
Restart=always
Environment=USER=git HOME=/home/git FORGEJO_WORK_DIR=/var/lib/forgejo
RestartSec=10s

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now forgejo

Configuración Inicial

Al acceder por primera vez a http://TU_IP:3000, se muestra el asistente de configuración. Los ajustes clave en /etc/forgejo/app.ini o /opt/forgejo/data/forgejo/conf/app.ini:

[server]
DOMAIN           = git.tudominio.com
ROOT_URL         = https://git.tudominio.com/
HTTP_PORT        = 3000
# SSH en puerto alternativo para evitar conflictos
SSH_PORT         = 2222
SSH_LISTEN_PORT  = 22

[repository]
# Tamaño máximo permitido por repositorio (en MB)
MAX_CREATION_LIMIT = -1  ; Sin límite

[security]
INSTALL_LOCK   = true
SECRET_KEY     = GENERA_UNA_CLAVE_ALEATORIA_AQUI
MIN_PASSWORD_LENGTH = 12
PASSWORD_COMPLEXITY = lower,upper,digit,spec

[service]
DISABLE_REGISTRATION = false  ; Cambiar a true para instancias privadas
REQUIRE_SIGNIN_VIEW  = false

[mailer]
ENABLED   = true
FROM      = [email protected]
PROTOCOL  = smtp
SMTP_ADDR = mail.tudominio.com
SMTP_PORT = 587
USER      = [email protected]
PASSWD    = TU_CONTRASEÑA_SMTP

Forgejo Actions CI/CD

Habilita Forgejo Actions en la configuración:

# En app.ini
[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://code.forgejo.org

Descarga e instala el runner:

# Descargar forgejo-runner
wget https://code.forgejo.org/forgejo/runner/releases/download/v3.5.0/forgejo-runner-3.5.0-linux-amd64 \
  -O /usr/local/bin/forgejo-runner
chmod +x /usr/local/bin/forgejo-runner

# Registrar el runner (obtén el token desde Ajustes del sitio > Actions)
forgejo-runner register \
  --instance https://git.tudominio.com \
  --token TU_TOKEN \
  --name "runner-principal" \
  --labels "ubuntu-latest,docker"

# Crear servicio systemd para el runner
sudo tee /etc/systemd/system/forgejo-runner.service << 'EOF'
[Unit]
Description=Forgejo Runner
After=network.target forgejo.service

[Service]
Type=simple
User=git
WorkingDirectory=/var/lib/forgejo-runner
ExecStart=/usr/local/bin/forgejo-runner daemon
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now forgejo-runner

Ejemplo de workflow en .forgejo/workflows/build.yml:

on: [push, pull_request]

jobs:
  build:
    runs-on: docker
    container:
      image: node:20-alpine
    steps:
      - uses: actions/checkout@v4
      - name: Instalar dependencias
        run: npm ci
      - name: Pruebas
        run: npm test
      - name: Construir
        run: npm run build

Federación entre Instancias

Forgejo implementa el protocolo ForgeFed para federar entre instancias (experimental):

# En app.ini - habilitar federación
[federation]
ENABLED = true

# Seguir los avances de la federación en:
# https://codeberg.org/forgejo/forgejo/issues/59

# Para ahora, puedes hacer mirrors cross-instancia via API:
curl -X POST "https://git.tudominio.com/api/v1/repos/migrate" \
  -H "Authorization: token TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clone_addr": "https://otra-instancia.org/usuario/repo.git",
    "repo_name": "repo-externo",
    "mirror": true,
    "mirror_interval": "24h"
  }'

Migración desde Gitea

Forgejo es compatible al 100% con Gitea a nivel de datos y configuración:

# Hacer backup de Gitea antes de migrar
gitea dump --config /etc/gitea/app.ini \
  --file /tmp/gitea-backup.zip

# Parar Gitea
sudo systemctl stop gitea

# Instalar Forgejo usando el mismo directorio de datos
# Forgejo puede leer directamente los datos de Gitea

# Cambiar el binario
sudo mv /usr/local/bin/gitea /usr/local/bin/gitea.bak
sudo cp /usr/local/bin/forgejo /usr/local/bin/gitea

# O crear un enlace simbólico
sudo ln -sf /usr/local/bin/forgejo /usr/local/bin/gitea

# Actualizar el servicio systemd para apuntar a forgejo
sudo sed -i 's|gitea web|forgejo web|g' /etc/systemd/system/gitea.service

sudo systemctl daemon-reload
sudo systemctl start gitea

# Verificar que todo funciona correctamente
sudo journalctl -u gitea -f

Solución de Problemas

Forgejo no arranca tras la migración:

# Verificar permisos de los datos
sudo chown -R git:git /var/lib/forgejo
sudo chown -R git:git /etc/forgejo

# Ver logs detallados
sudo journalctl -u forgejo -n 100 --no-pager
cat /var/lib/forgejo/log/forgejo.log

SSH no funciona:

# Verificar que el puerto SSH de Forgejo está escuchando
sudo ss -tlnp | grep 22

# Comprobar el fichero authorized_keys de git
sudo cat /home/git/.ssh/authorized_keys

# Regenerar las claves de acceso SSH
sudo -u git forgejo admin regenerate keys

Problemas con el runner:

# Ver configuración del runner
cat ~/.runner

# Verificar que el runner aparece en Forgejo
# Ve a: Admin > Actions > Runners

Conclusión

Forgejo ofrece una plataforma Git autoalojada mantenida por la comunidad, con compatibilidad total con Gitea y una hoja de ruta enfocada en gobernanza abierta y fedearción. Su instalación con Docker es la opción más rápida para entornos de producción, mientras que la instalación nativa permite un control más fino sobre el sistema. La integración con Forgejo Actions proporciona un sistema CI/CD completo sin necesidad de herramientas adicionales.