Déployer avec Kamal

Kamal (v2) déploie TrocOS sur n'importe quel VPS via Docker. Il gère les déploiements sans interruption, le SSL et un conteneur PostgreSQL comme accessoire. Cette option vous offre le plus de contrôle et les coûts les plus bas.

Prérequis

• Un VPS sous Ubuntu 22.04+ (ex : Hetzner, OVH, DigitalOcean) — minimum 1 vCPU / 1 Go de RAM
• Docker installé sur le VPS : curl -fsSL https://get.docker.com | sh
• Un compte sur un registre de conteneurs (Docker Hub, GitLab Registry ou GitHub Container Registry)
• Le DNS de votre domaine pointant vers l'IP du VPS
• Ruby 3.2+ et la gem kamal sur votre machine locale : gem install kamal

1. Configurer config/deploy.yml

Éditez config/deploy.yml dans le dépôt TrocOS. Voici un point de départ annoté :

service: trocos
image: registry.example.com/yourorg/trocos

servers:
  web:
    hosts:
      - VOTRE_IP_VPS

# kamal-proxy gère le routage et le SSL (remplace Traefik de la v1)
proxy:
  host: votre-domaine.com
  app_port: 3000
  ssl: true                    # Let's Encrypt automatique
  healthcheck:
    path: /up

registry:
  server: registry.example.com
  username: votre_utilisateur
  password:
    - KAMAL_REGISTRY_PASSWORD  # résolu depuis .kamal/secrets

builder:
  arch: amd64

env:
  secret:
    - DATABASE_URL
  clear:
    RAILS_ENV: production

accessories:
  postgres:
    image: postgres:16
    host: VOTRE_IP_VPS
    port: "127.0.0.1:5432:5432"
    env:
      clear:
        POSTGRES_DB: trocos_production
        POSTGRES_USER: trocos
      secret:
        - POSTGRES_PASSWORD
    directories:
      - postgres-data:/var/lib/postgresql/data

2. Créer .kamal/secrets

Ce fichier est chargé avant chaque déploiement. Ne le committez pas dans git.

# .kamal/secrets
KAMAL_REGISTRY_PASSWORD=votre_mot_de_passe_registre
POSTGRES_PASSWORD=choisissez_un_mot_de_passe_fort
DATABASE_URL="postgres://trocos:${POSTGRES_PASSWORD}@trocos-postgres/trocos_production"

Ajoutez .kamal/secrets à votre .gitignore.

Kamal v2 vs v1

Kamal v2 utilise proxy: (et non traefik:), .kamal/secrets (et non .env), et le SSL se configure avec ssl: true sous proxy:. Si vous migrez depuis la v1, consultez le guide de migration Kamal.

3. Premier déploiement

# Démarrer l'accessoire PostgreSQL en premier
kamal accessory boot postgres

# Construire l'image, la pousser et déployer
kamal setup

4. Migrations et configuration initiale

kamal app exec 'bin/rails db:migrate'
kamal app exec 'bin/rails trocos:setup'

La tâche trocos:setup crée votre premier compte administrateur.

5. Déploiements suivants

kamal deploy

Kamal effectue un déploiement progressif sans interruption de service.

Commandes utiles

kamal app logs                          # Suivre les logs de l'application
kamal app exec 'bin/rails console'      # Ouvrir la console Rails
kamal app exec 'bin/rails db:migrate'   # Exécuter les migrations en attente
kamal accessory logs postgres           # Logs PostgreSQL