Instalación de Docker: inicie gitrust en 30 minutos con docker-compose¶

Objetivos¶

Al final de este tutorial, sabrás:

• O1. Implemente la pila mínima de gitrust (aplicación + PostgreSQL) con docker-compose
• O2. Verifique que los tres servicios se inicien correctamente y estén en buen estado
• O3. Cree la primera cuenta de administrador y acceda a la interfaz web

Requisitos previos¶

• Técnico: una máquina virtual o Linux (Debian 12 / Ubuntu 22.04 o superior), Docker Engine ≥ 24 instalado (docker --version responde), complemento Docker Compose instalado (docker compose version responde), puertos 4000 y 2222 libres en la máquina
• Image Docker gitrust : à construire localement à partir du code source (l'image n'est pas encore publiée sur un registre public). Suivez la section Construire l'image gitrust ci-dessous avant le docker compose up.
• Educativo: no se requiere tutorial previo de Gitrust: este es el punto de partida del recorrido del administrador
• Tiempo estimado: ~30 minutos

Construire l'image gitrust¶

git clone https://demo.gitrust.eu/gitrust/gitrust.git
cd gitrust
docker build -t gitrust:latest .

À la fin, docker image ls | grep gitrust doit afficher l'image locale gitrust:latest. Le build prend ~8-15 min (compilation Rust en release + build CSS Tailwind). Si vous rencontrez une erreur, ouvrez une issue sur le dépôt source — le pipeline Docker n'a pas encore été testé en production.

Descripción general¶

Antes de ejecutar cualquier comando, comprendamos qué orquestará docker-compose y por qué.

gitrust se compone de tres servicios principales en su configuración mínima. Piense en ello como tres habitaciones de un apartamento que se llaman entre sí a través de una red interna:

graph TB
    subgraph internet ["Internet / votre navigateur"]
        B[Navigateur :4000]
        S[Client git/SSH :2222]
    end

    subgraph docker ["Réseau Docker gitrust_net"]
        A["gitrust-app
(Rust, port 4000 + 2222)
Lit la config depuis .env"]
        P["postgres
(PostgreSQL 16, port 5432)
Stocke comptes, dépôts, issues"]
        R["redis (optionnel)
(Redis 7, port 6379)
Sessions web + cache"]
    end

    B -->|HTTP| A
    S -->|SSH| A
    A -->|SQL| P
    A -.->|sessions| R

gitrust-app es el núcleo: servidor HTTP (:4000) + servidor SSH (:2222) compilado en Rust. Lee su configuración de un archivo .env y escribe repositorios Git desnudos en un volumen Docker. PostgreSQL almacena todos los datos relacionales (cuentas, organizaciones, repositorios, problemas, relaciones públicas). Redis es opcional en la configuración mínima: administra las sesiones web y el caché cuando está presente.

Dans ce tutoriel, nous utilisons la stack minimale (app + PostgreSQL) suffisante pour évaluer gitrust et démarrer une petite instance. La stack production avec Redis et SMTP se trouve dans template/docker/docker-compose.production.yml.

Paso 1: cree el directorio de trabajo y el archivo de configuración¶

Crea un directorio dedicado a tu instancia de gitrust y ubícate en él:

mkdir -p /opt/gitrust && cd /opt/gitrust

Cree el archivo de configuración .env con los valores mínimos. Debe cambiar los valores marcados CHANGE_ME:

cat > .env << 'EOF'
# === gitrust — configuration minimale ===
# Changez toutes les valeurs CHANGE_ME avant de démarrer

# Clé secrète de l'application (générez avec : openssl rand -hex 32)
SECRET_KEY=CHANGE_ME_openssl_rand_hex_32

# URL publique de l'instance (sans slash final)
APP_URL=http://localhost:4000

# Base de données PostgreSQL
DATABASE_URL=postgres://gitrust:CHANGE_ME_db_password@postgres:5432/gitrust
POSTGRES_USER=gitrust
POSTGRES_PASSWORD=CHANGE_ME_db_password
POSTGRES_DB=gitrust

# Serveur SSH (port exposé à l'extérieur)
SSH_PORT=2222

# Mode de l'application
RUST_LOG=info
APP_ENV=production
EOF

Ahora genere una clave secreta sólida y reemplace el valor en .env:

SECRET=$(openssl rand -hex 32)
sed -i "s/CHANGE_ME_openssl_rand_hex_32/$SECRET/" .env

Elija también una contraseña para PostgreSQL y reemplace ambas apariciones:

DB_PASS=$(openssl rand -hex 16)
sed -i "s/CHANGE_ME_db_password/$DB_PASS/g" .env

Resultado esperado (verificación):

grep SECRET_KEY .env
# → SECRET_KEY=4a7f2c9e1b8d3f6a0e5c2b9d7f4a1e8c3b6d9f2a5e8c1b4d7f0a3e6c9b2d5f8a

Punto de control: ejecute grep CHANGE_ME .env; el comando no debería devolver nada. Si devuelve filas, estos valores no han sido reemplazados y el inicio fallará.

Paso 2: cree el archivo docker-compose.yml¶

Cree el siguiente archivo docker-compose.yml en /opt/gitrust/. Este contenido corresponde a la pila mínima de gitrust; se reproduce aquí en su totalidad para que pueda comenzar sin dependencias externas:

cat > docker-compose.yml << 'EOF'
# docker-compose.minimal.yml — Stack gitrust minimale (app + PostgreSQL)
# Cas d'usage : évaluation, développement, petite instance (<10 utilisateurs)
# Pour la production : utilisez docker-compose.production.yml (+ Redis + SMTP)
#
# Usage :
#   docker compose up -d
#   docker compose logs -f gitrust
#   docker compose down

version: "3.9"

services:
  # ── Base de données ───────────────────────────────────────────────────────
  postgres:
    image: postgres:16-alpine
    container_name: gitrust_postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      # Données persistantes — ne supprimez pas ce volume sans sauvegarde
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - gitrust_net

  # ── Application gitrust ───────────────────────────────────────────────────
  gitrust:
    image: gitrust:latest
    container_name: gitrust_app
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    env_file:
      # Lit toutes les variables depuis .env — ne commitez jamais ce fichier
      - .env
    ports:
      # Interface web — exposée sur toutes les interfaces de la machine hôte
      - "4000:4000"
      # Serveur SSH Git — exposé sur le port configuré dans .env
      - "${SSH_PORT:-2222}:2222"
    volumes:
      # Dépôts Git bare — données critiques, sauvegardez ce volume
      - git_repos:/var/lib/gitrust/repositories
      # Clés SSH du serveur — générées au premier démarrage, persistez-les
      - ssh_host_keys:/etc/gitrust/ssh
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    networks:
      - gitrust_net

volumes:
  # postgres_data : données relationnelles (comptes, dépôts, issues, PRs)
  postgres_data:
  # git_repos : dépôts Git bare (le contenu réel des commits)
  git_repos:
  # ssh_host_keys : clés SSH hôte (fingerprint de votre serveur)
  ssh_host_keys:

networks:
  gitrust_net:
    driver: bridge
EOF

Punto de control: compruebe que ambos archivos estén presentes en /opt/gitrust/:

ls -la /opt/gitrust/

Resultado esperado:

total 16
drwxr-xr-x 2 root root 4096 avr 17 10:00 .
drwxr-xr-x 8 root root 4096 avr 17 09:55 ..
-rw------- 1 root root  612 avr 17 10:00 .env
-rw-r--r-- 1 root root 2048 avr 17 10:00 docker-compose.yml

Paso 3: inicie la pila y siga los registros¶

Inicie todos los servicios en segundo plano:

docker compose up -d

Resultado esperado:

[+] Running 4/4
 ✔ Network gitrust_gitrust_net    Created                          0.1s
 ✔ Volume "gitrust_postgres_data" Created                          0.0s
 ✔ Container gitrust_postgres     Started                          0.8s
 ✔ Container gitrust_app          Started                          1.2s

Siga los registros de la aplicación para observar el inicio (las migraciones se ejecutan automáticamente):

docker compose logs -f gitrust

Resultado esperado (primeros 15 a 20 segundos):

gitrust_app  | 2026-04-17T10:00:15Z INFO  gitrust > Starting gitrust v0.9.0
gitrust_app  | 2026-04-17T10:00:15Z INFO  gitrust > Connecting to database...
gitrust_app  | 2026-04-17T10:00:16Z INFO  gitrust > Running database migrations...
gitrust_app  | 2026-04-17T10:00:17Z INFO  gitrust > Applied 42 migrations successfully
gitrust_app  | 2026-04-17T10:00:17Z INFO  gitrust > Generating SSH host keys...
gitrust_app  | 2026-04-17T10:00:17Z INFO  gitrust > SSH host key fingerprint: SHA256:xxxxxxxxxxxxxxxxxxxx
gitrust_app  | 2026-04-17T10:00:17Z INFO  gitrust > HTTP server listening on 0.0.0.0:4000
gitrust_app  | 2026-04-17T10:00:17Z INFO  gitrust > SSH server listening on 0.0.0.0:2222
gitrust_app  | 2026-04-17T10:00:17Z INFO  gitrust > gitrust is ready

Presione Ctrl+C para salir de la supervisión de registros (los contenedores continúan ejecutándose).

Punto de control: comprobar el estado de salud de los servicios:

docker compose ps

Resultado esperado:

NAME              IMAGE                          COMMAND                  SERVICE    CREATED         STATUS                   PORTS
gitrust_app       gitrust:latest "/usr/local/bin/gitr…"  gitrust    2 minutes ago   Up 2 minutes (healthy)   0.0.0.0:4000->4000/tcp, 0.0.0.0:2222->2222/tcp
gitrust_postgres  postgres:16-alpine             "docker-entrypoint.s…"  postgres   2 minutes ago   Up 2 minutes (healthy)   5432/tcp

Ambos contenedores deben mostrar "(saludable)". Si uno muestra "(iniciando)", espere 30 segundos y vuelva a intentar el comando. Si muestra "(no saludable)", verifique los registros con "docker compose logs gitrust" o "docker compose logs postgres".

Paso 4: crea la primera cuenta de administrador¶

Abra su navegador y vaya a http://localhost:4000.

Debería ver la página de inicio de gitrust con un formulario de registro. Como la instancia está en blanco, la primera cuenta creada se convierte automáticamente en administrador.

Remplissez le formulaire : - Pseudo: su identificador de administrador (por ejemplo, admin) - Correo electrónico: su dirección de correo electrónico - Contraseña: elija una contraseña segura (≥ 12 caracteres)

Haga clic en Crear mi cuenta.

Salida esperada en los registros (visible con docker compose logs -f gitrust):

gitrust_app  | 2026-04-17T10:05:00Z INFO  gitrust::auth > New user registered: admin (id=1)
gitrust_app  | 2026-04-17T10:05:00Z INFO  gitrust::admin > First user promoted to administrator: admin

Punto de control final: inicia sesión con tus credenciales. Después de iniciar sesión, verifique que el menú superior derecho muestre un enlace Administración (o navegue hasta http://localhost:4000/admin). Solo los administradores pueden acceder a esta página; su presencia confirma que su cuenta tiene la función de administrador.

La URL de su instancia es http://localhost:4000 y su cuenta de administrador está operativa.

Resumen¶

• ✓ O1 completado: la pila docker-compose está implementada: docker compose ps muestra dos contenedores (en buen estado)
• ✓ O2 logrado: los tres servicios (aplicación, PostgreSQL, red interna) se inician correctamente: los registros muestran "gitrust está listo" y se aplican las migraciones
• ✓ O3 logrado: se crea la primera cuenta de administrador y se puede acceder a la página /admin

Y si no funciona¶

Siguiente paso¶

→ 02 — Instalación de Systemd: binario nativo + servicio: descubra la instalación sin Docker para una implementación de producción con refuerzo de AppArmor (~45 min)

O si desea que esta instancia sea accesible desde Internet:

→ 04 — Puesta en producción: proxy inverso TLS, SMTP, copia de seguridad automática (~90 min)