Instalação do Docker: inicie o gitrust em 30 minutos com docker-compose¶

Metas¶

Ao final deste tutorial, você saberá:

• O1. Implante a pilha gitrust mínima (aplicativo + PostgreSQL) com docker-compose
• O2. Verifique se todos os três serviços iniciam corretamente e estão íntegros
• O3. Crie a primeira conta de administrador e acesse a interface web

Pré-requisitos¶

• Técnico: uma máquina VM ou Linux (Debian 12 / Ubuntu 22.04 ou superior), Docker Engine ≥ 24 instalado (docker --version responde), plugin Docker Compose instalado (docker compose version responde), portas 4000 e 2222 livres na 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.
• Educacional: não é necessário nenhum tutorial anterior do gitrust — este é o ponto de partida da jornada do administrador
• Tempo 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.

Visão geral¶

Antes de lançar qualquer comando, vamos entender o que o docker-compose irá orquestrar e por quê.

gitrust é composto por três serviços principais em sua configuração mínima. Pense nisso como três quartos de um apartamento ligando entre si através de uma rede 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 é o núcleo: servidor HTTP (:4000) + servidor SSH (:2222) compilado em Rust. Ele lê sua configuração de um arquivo .env e grava repositórios Git simples em um volume Docker. PostgreSQL armazena todos os dados relacionais (contas, organizações, repositórios, problemas, PRs). Redis é opcional na configuração mínima — ele gerencia sessões web e cache quando 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.

Etapa 1: Crie o diretório de trabalho e o arquivo de configuração¶

Crie um diretório dedicado à sua instância gitrust e posicione-se nele:

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

Crie o arquivo de configuração .env com os valores mínimos. Deve alterar os valores marcados como 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

Agora gere uma chave secreta robusta e substitua o valor em .env:

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

Escolha também uma senha para o PostgreSQL e substitua ambas as ocorrências:

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

Resultado esperado (verificação):

grep SECRET_KEY .env
# → SECRET_KEY=4a7f2c9e1b8d3f6a0e5c2b9d7f4a1e8c3b6d9f2a5e8c1b4d7f0a3e6c9b2d5f8a

Ponto de verificação: execute grep CHANGE_ME .env — o comando não deve retornar nada. Se retornar linhas, esses valores não foram substituídos e a inicialização falhará.

Etapa 2: crie o arquivo docker-compose.yml¶

Crie o seguinte arquivo docker-compose.yml em /opt/gitrust/. Este conteúdo corresponde à pilha mínima do gitrust — ele é reproduzido aqui na íntegra para que você possa começar sem dependências 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

Ponto de verificação: verifique se ambos os arquivos estão presentes em /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

Etapa 3: inicie a pilha e siga os registros¶

Inicie todos os serviços em 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 os logs do aplicativo para observar a inicialização (as migrações são executadas automaticamente):

docker compose logs -f gitrust

Resultado esperado (primeiros 15-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

Pressione Ctrl+C para sair do monitoramento de log (os contêineres continuam em execução).

Ponto de verificação: verifique o estado de saúde dos serviços:

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 os contêineres devem exibir (saudável). Se alguém exibir (iniciando), aguarde 30 segundos e tente novamente o comando. Se mostrar (não íntegro), verifique os logs com docker compose logs gitrust ou docker compose logs postgres.

Etapa 4: crie a primeira conta de administrador¶

Abra seu navegador e vá para http://localhost:4000.

Você deverá ver a página inicial do gitrust com um formulário de registro. Como a instância está em branco, a primeira conta criada torna-se automaticamente administrador.

Remplissez le formulaire : - Pseudo: seu identificador de administrador (por exemplo, admin) - E-mail: seu endereço de e-mail - Senha: escolha uma senha forte (≥ 12 caracteres)

Clique em Criar minha conta.

Saída esperada nos logs (visível com 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

Ponto de verificação final: faça login com suas credenciais. Após fazer login, verifique se o menu superior direito mostra um link Administração (ou navegue até http://localhost:4000/admin). Esta página só é acessível a administradores – sua presença confirma que sua conta tem a função de administrador.

O URL da sua instância é http://localhost:4000 e sua conta de administrador está operacional.

Resumo¶

• ✓ O1 realizado: a pilha docker-compose é implantada — docker compose ps exibe dois contêineres (saudáveis)
• ✓ O2 realizado: os três serviços (app, PostgreSQL, rede interna) iniciam corretamente — os logs mostram “gitrust está pronto” e as migrações são aplicadas
• ✓ O3 realizado: a primeira conta de administrador é criada e a página /admin está acessível

E se não funcionar¶

Próxima etapa¶

→ 02 — Instalação do Systemd: binário nativo + serviço: descubra a instalação sem Docker para uma implantação de produção com proteção AppArmor (~45 min)

Ou se você quiser tornar esta instância acessível pela Internet:

→ 04 — Colocado em produção: TLS de proxy reverso, SMTP, backup automático (~90 min)