Instalacion con Docker Compose

Docker Compose es la forma mas rapida de tener Forgejo funcionando sin afectar el sistema anfitrion. Todo corre en contenedores aislados.

Requisitos previos

• Docker Engine 24 o superior instalado
• Docker Compose plugin (incluido en Docker Desktop o instalable con apt install docker-compose-plugin)
• Puerto 3000 y 22 disponibles en el servidor

Verificar que ambos estan disponibles:

docker --version
docker compose version

Estructura de directorios

Crea un directorio dedicado para el proyecto:

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

docker-compose.yml

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

volumes:
  forgejo-data:

Puntos clave del archivo:

• imagen fija (forgejo:14): no usar latest para evitar actualizaciones inesperadas que rompan la instalacion
• USER_UID / USER_GID: el proceso dentro del contenedor corre con el UID/GID del usuario anfitrion, evitando problemas de permisos en el volumen
• timezone: se monta de solo lectura para que los logs y commits muestren la hora correcta
• restart: unless-stopped: el contenedor se reinicia automaticamente tras reboot, excepto si fue detenido manualmente

Primer arranque

docker compose up -d

El flag -d (detached) lo ejecuta en segundo plano. Para verificar que el contenedor levanto correctamente:

docker compose ps
docker compose logs -f forgejo

Espera ver en los logs una linea similar a:

forgejo  | Starting new Web server: tcp:0.0.0.0:3000

Verificar acceso

Abre el navegador en http://localhost:3000. Si el servidor es remoto, reemplaza localhost por la IP del servidor.

En el primer acceso Forgejo muestra el asistente de instalacion inicial. La configuracion de ese asistente se cubre en el capitulo 5.

Estructura de datos en el volumen

Forgejo crea la siguiente estructura dentro del volumen forgejo-data (montado en /data del contenedor):

/data/
  gitea/
    conf/
      app.ini         <- archivo de configuracion principal
    log/              <- logs de la aplicacion
  git/
    repositories/     <- repositorios Git almacenados
  ssh/                <- claves SSH del servidor

El directorio critico es /data/gitea/conf/app.ini. Cualquier cambio manual en ese archivo requiere reiniciar el contenedor:

docker compose restart forgejo

SQLite como base de datos

Esta configuracion usa SQLite, que almacena todos los datos en un unico archivo dentro del volumen:

/data/gitea/gitea.db

SQLite es adecuado para equipos pequenos o uso personal (hasta ~50 usuarios activos). No requiere instalar ni configurar un servidor de base de datos separado, lo que simplifica el mantenimiento inicial.

Para equipos mas grandes o si necesitas alta disponibilidad, el capitulo 20 cubre la migracion a PostgreSQL.

Comandos de gestion

# Detener Forgejo
docker compose down

# Detener y eliminar volumenes (ELIMINA TODOS LOS DATOS)
docker compose down -v

# Actualizar a nueva version (edita la imagen en docker-compose.yml primero)
docker compose pull
docker compose up -d

# Ver logs en tiempo real
docker compose logs -f forgejo

---

Siguiente: Capitulo 5: Configuracion inicial —>