🚀 Coolify + Astro + Directus

1. Vue d’ensemble de la stack

Cette stack assemble quatre composants distincts pour produire un site vitrine statique performant, gérable via une interface de contenu, et déployé automatiquement à chaque modification.

Rôle de chaque composant

Cycle complet de mise à jour

1. Le gestionnaire de contenu modifie ou crée un item dans Directus (ex : nouvelle offre de service)
2. Le Flow Directus se déclenche sur l’événement items.update
3. Le Flow effectue un POST HTTP vers l’API Coolify avec l’UUID de l’application et le paramètre &force=true
4. Coolify lance un docker build --no-cache du projet Astro
5. Pendant le build, Astro fetch toutes les collections Directus via l’API REST
6. Astro génère le dist/ statique avec les nouvelles données
7. nginx Alpine est construit avec le nouveau dist/
8. Coolify remplace l’ancien container par le nouveau (zero-downtime si configuré)
9. Le site est à jour

2. Limites de Directus côté usage client

Problèmes d’ergonomie pour les non-techniques

• Interface pensée développeur, pas end-user : La terminologie exposée est celle d’une base de données — on parle de "Collections", "Items", "Fields", "Relations" — pas de "Pages", "Articles", "Titre de la page". Un gestionnaire de contenu non-technique sera perdu dès le premier écran.
• Pas de WYSIWYG par défaut : Les champs texte longs sont de simples zones de saisie. Il faut configurer manuellement le type d’interface à Rich Text (WYSIWYG via TipTap) ou Markdown dans les paramètres de chaque champ. Ce n’est pas intuitif et ce n’est pas aussi riche qu’un éditeur WordPress ou Ghost.
• Logique base de données exposée : Chaque collection correspond à une table, chaque item à une ligne. Les relations (Many-to-Many, One-to-Many) se configurent en base. Pour un utilisateur habituelé à un CMS classique, naviguer entre collections liées est déroutant.
• Flows (webhooks internes) : L’outil d’automatisation de Directus est puissant mais la courbe d’apprentissage est élevée. L’interface de création de flows est peu intuitive (système de nodes à connecter visuellement). Un administrateur non-développeur ne peut pas le gérer seul.
• Pas de versionning de contenu natif : Contrairement à WordPress (révisions d’articles), Directus ne conserve pas l’historique des modifications d’un item. Si un utilisateur écrase une valeur, elle est perdue. Des extensions tierces existent mais ne sont pas activées par défaut.
• Pas adapté pour les TPE/PME sans référent technique : Si aucune personne technique n’est disponible côté client pour former et accompagner les utilisateurs, Directus génère du support inutile. Dans ce cas, préférer WordPress, Ghost, ou Strapi (meilleure UX admin).

Profil idéal pour Directus

3. Prérequis

• 🖥 VPS Debian 12 minimum — 2 Go RAM (4 Go recommandé pour Coolify + Directus + app + PostgreSQL). CPU : 2 vCPU minimum. Stockage : 20 Go SSD minimum.
• 🐳 Docker installé — Coolify peut l’installer automatiquement mais avoir une version récente (24+) est préférable. docker --version && docker compose version
• 💻 Compte GitHub avec un token d’accès personnel — scope requis : repo (lecture/écriture sur les repos privés). Le token est nécessaire pour que Coolify accède au code source et configure les webhooks automatiquement.
• 🌐 Domaine ou entrée DNS — Un domaine pointé sur l’IP du VPS (entrée A en DNS). Pour un test local, une entrée dans /etc/hosts suffit. Coolify gère ensuite le SSL automatiquement via Let’s Encrypt si le domaine est accessible depuis internet.
• 🔒 Port 8001 ouvert — Pour accéder à l’interface Coolify. Ports 80 et 443 ouverts pour le trafic web.
• 📦 Node.js 18+ en local — Pour développer le projet Astro en local avant de pusher sur GitHub.

4. Installation Coolify

Script d’installation officiel

Coolify s’installe en une seule commande en root sur le VPS :

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

Le script installe Docker si absent, configure les réseaux Docker, télécharge les images Coolify et démarre l’interface web. L’installation complète prend 3 à 5 minutes selon la connexion.

Accès à l’interface

Coolify écoute sur le port 8000 par défaut. Accéder via : http://[IP-VPS]:8000

nano /data/coolify/source/.env
# Changer APP_PORT=8000 en APP_PORT=8001 (ou tout autre port libre)

# Puis relancer :
cd /data/coolify/source && docker compose up -d

Créer un token API Coolify

Le token est nécessaire pour que Directus puisse appeler l’API Coolify et déclencher les rebuilds.

1. Se connecter à l’interface Coolify
2. Cliquer sur Profile (icône en haut à droite)
3. API Tokens → New Token
4. Donner un nom explicite : directus-deploy-webhook
5. Cocher TOUTES les permissions
6. Copier et sauvegarder le token généré (il ne sera plus affiché après)

⚠ ALERTE CRITIQUE : conflit réseau Docker

# Créer ou modifier /etc/docker/daemon.json
nano /etc/docker/daemon.json

{
  "default-address-pools": [
    {"base": "172.20.0.0/16", "size": 24}
  ]
}

# Appliquer le changement
systemctl restart docker

# Vérifier que les containers Coolify redémarrent bien
docker ps

5. Déploiement Directus via Coolify

Création du service

1. Dans Coolify : Services → + New Service
2. Rechercher directus dans la liste
3. Sélectionner directus-with-postgresql (inclut PostgreSQL dédié pour Directus)
4. Choisir l’environnement cible (serveur + réseau)
5. Configurer les variables d’environnement essentielles

Variables d’environnement Directus

ADMIN_EMAIL=admin@votredomaine.re
ADMIN_PASSWORD=MotDePasseForte2024!
SECRET=une-chaine-aleatoire-longue-32-caracteres-minimum

# Optionnel mais recommandé
PUBLIC_URL=https://cms.votredomaine.re
CORS_ENABLED=true
CORS_ORIGIN=https://votredomaine.re

Récupérer l’IP Docker interne de Directus

Une fois Directus déployé et démarré, récupérer son IP interne Docker. C’est cette IP qu’Astro utilisera pour fetcher l’API au moment du build.

# Lister les containers pour trouver le nom du container Directus
docker ps | grep directus

# Inspecter le container pour obtenir son IP
docker inspect [nom-container-directus] | grep IPAddress

# Exemple de résultat :
# "IPAddress": "172.20.2.4"

Configurer les collections dans Directus

1. Accéder à l’interface Directus : http://[IP-VPS]:port-directus ou via le domaine configuré
2. Se connecter avec les credentials ADMIN_EMAIL / ADMIN_PASSWORD
3. Aller dans Settings → Data Model
4. Créer les collections : services, tarifs, temoignages, equipe...
5. Pour chaque collection, définir les champs (nom, description, ordre, actif, image...)
6. Pour les champs texte longs : choisir l’interface Rich Text ou Markdown

Configurer les permissions publiques

1. Settings → Access Control → Public
2. Pour chaque collection (services, tarifs, etc.) : cocher Read
3. Ne jamais cocher Create/Update/Delete pour le rôle Public

# Tester l'API publique depuis le VPS :
curl http://172.20.2.4:8055/items/services
# Doit retourner un JSON avec les items (pas une erreur 403)

6. Connecter Directus au réseau Coolify

Par défaut, Directus est déployé dans son propre réseau Docker isolé. L’application Astro (pendant son build) se trouve dans le réseau coolify. Ces deux réseaux ne se voient pas.

Solution : connecter Directus au réseau coolify

# Connecter le container Directus au réseau coolify
docker network connect coolify [nom-container-directus]

# Vérifier que la connexion est active :
docker inspect [nom-container-directus] | grep -A5 '"coolify"'

# Vous devez voir quelque chose comme :
# "coolify": {
#     "IPAMConfig": {},
#     "Links": null,
#     "Aliases": ["directus"],
#     "IPAddress": "172.20.0.15"
# }

Utiliser l’IP interne Docker dans Astro

Dans le code Astro, utiliser l’IP Docker interne de Directus (pas localhost, pas le domaine public). L’IP interne est stable tant que le container n’est pas recréé.

// Dans le code Astro
const DIRECTUS = 'http://172.20.2.4:8055';

// Alternative plus robuste : variable d'environnement
// DIRECTUS_URL=http://172.20.2.4:8055 dans les env vars Coolify
const DIRECTUS = import.meta.env.DIRECTUS_URL;

7. Création du projet Astro

Initialisation

npm create astro@latest
# Choix recommandés :
# Template : Empty
# TypeScript : No (ou Strict si l’équipe maîtrise TS)
# Install dependencies : Yes
# Init git : Yes

cd mon-site-vitrine
npm run dev  # Vérifier que le projet démarre sur http://localhost:4321

Configuration astro.config.mjs

import { defineConfig } from 'astro/config';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  output: 'static',   // Mode SSG : génère dist/ statique
  vite: {
    plugins: [tailwindcss()],
  },
});

Installer Tailwind CSS (optionnel mais recommandé pour les sites vitrine) :

npm install -D @tailwindcss/vite tailwindcss

Fetch Directus dans une page Astro

Les pages .astro ont un bloc frontmatter (entre ---) exécuté uniquement au build time. C’est là que se font les appels API vers Directus :

---
// src/pages/index.astro

const DIRECTUS = import.meta.env.DIRECTUS_URL ?? 'http://172.20.2.4:8055';

// Fetch parallèle de plusieurs collections
const [servicesRes, tarifsRes, temoignagesRes] = await Promise.all([
  fetch(`${DIRECTUS}/items/services?sort=ordre&filter[actif][_eq]=true`),
  fetch(`${DIRECTUS}/items/tarifs?sort=ordre`),
  fetch(`${DIRECTUS}/items/temoignages?sort=-date_created&limit=6`),
]);

// Extraire les données (Directus enveloppe toujours dans { data: [...] })
const services = (await servicesRes.json()).data ?? [];
const tarifs = (await tarifsRes.json()).data ?? [];
const temoignages = (await temoignagesRes.json()).data ?? [];
---

<!-- Template HTML Astro -->
<html lang="fr">
  <head>
    <meta charset="UTF-8">
    <title>Mon Site Vitrine</title>
  </head>
  <body>
    <section id="services">
      <h2>Nos Services</h2>
      {services.map(service => (
        <article>
          <h3>{service.nom}</h3>
          <p>{service.description}</p>
        </article>
      ))}
    </section>

    <section id="tarifs">
      <h2>Nos Tarifs</h2>
      {tarifs.map(tarif => (
        <div class="tarif-card">
          <h3>{tarif.nom}</h3>
          <p class="prix">{tarif.prix} €/mois</p>
          <p>{tarif.description}</p>
        </div>
      ))}
    </section>
  </body>
</html>

Structure de projet recommandée

mon-site-vitrine/
├── src/
│   ├── pages/
│   │   ├── index.astro          # Page d’accueil
│   │   ├── services.astro       # Page services
│   │   └── contact.astro        # Page contact
│   ├── components/
│   │   ├── Header.astro
│   │   ├── Footer.astro
│   │   └── ServiceCard.astro
│   └── layouts/
│       └── Base.astro           # Layout générique
├── public/                      # Assets statiques (images, favicon)
├── astro.config.mjs
├── Dockerfile               # ◀ Créer ce fichier (voir section 8)
└── package.json

8. Dockerfile multistage (nginx)

Le Dockerfile utilise un build multistage : une première image Node.js compile le projet Astro, une deuxième image nginx légère sert uniquement le contenu statique généré.

# Stage 1 : Build Astro
FROM node:22-bookworm-slim AS builder
WORKDIR /app

# Copier les manifestes de dépendances en premier (cache Docker optimal)
COPY package*.json ./
RUN npm ci --legacy-peer-deps

# Copier le code source
COPY . .

# Build : Astro fetch Directus et génère dist/
RUN npm run build

# Stage 2 : Servir avec nginx Alpine (image finale légère)
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80

Pourquoi ce pattern ?

• Sécurité : L’image finale ne contient pas Node.js, npm, ni le code source. Seuls les fichiers HTML/CSS/JS statiques sont présents.
• Performance : nginx Alpine fait ~25 Mo. nginx sert du statique très efficacement, sans overhead.
• Data fetch au build time : pendant le npm run build du stage 1, Astro appellle http://172.20.2.4:8055/items/... et intègre les données dans le HTML généré. En production, aucune requête API n’est effectuée.
• Cache Docker : La copie des package*.json et le npm ci avant le COPY . . permettent à Docker de cacher la couche d’installation des dépendances si celles-ci n’ont pas changé. Mais attention : si Coolify utilise --no-cache (via force=true), toutes les couches sont reconstruites.

Configuration nginx personnalisée (optionnel)

Pour ajouter la gestion des routes SPA ou des en-têtes de sécurité :

# nginx.conf à placer à la racine du projet
server {
    listen 80;
    root /usr/share/nginx/html;
    index index.html;

    # Gestion 404 : renvoyer vers index.html (si routing côté client)
    location / {
        try_files $uri $uri/ /index.html;
    }

    # En-têtes de sécurité
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";
    add_header Referrer-Policy "strict-origin-when-cross-origin";

    # Cache des assets statiques
    location ~* \.(js|css|png|jpg|svg|ico|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

# Dans le Dockerfile, remplacer le stage 2 par :
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80

9. Configuration de l’application dans Coolify

Création de l’application

1. New Application → GitHub
2. Sélectionner le repository du projet Astro
3. Choisir la branche (généralement main)
4. Build Pack : Dockerfile — IMPORTANT : ne pas choisir Nixpacks. Nixpacks détecte automatiquement Node.js et tente de lancer npm start au lieu de servir le statique via nginx.
5. Dockerfile location : /Dockerfile (à la racine du repo)
6. Port exposé : 80 (port nginx, pas 4321 qui est le port de dév Astro)
7. Domain : votre domaine (ex: www.votredomaine.re)

Variables d’environnement de l’application

# Dans Coolify > Application > Environment Variables
DIRECTUS_URL=http://172.20.2.4:8055
# Ces variables sont injectées dans le container au build time
# et accessibles via import.meta.env dans Astro

Vérifications critiques via psql (base Coolify)

Coolify stocke la configuration des applications dans une base PostgreSQL interne. En cas de comportement anormal (mauvais port, crash au démarrage), vérifier directement en base :

# Se connecter à la base Coolify
docker exec -it coolify-db psql -U coolify

# Vérifier les paramètres clés de l'application
SELECT build_pack, ports_exposes, start_command, is_static
FROM applications
WHERE uuid='[votre-uuid-application]';

-- Résultat attendu :
-- build_pack     | ports_exposes | start_command | is_static
-- dockerfile     | 80            | (null)        | false

-- Corriger start_command s'il est renseigné (cause de crash)
UPDATE applications SET start_command = NULL WHERE uuid='[votre-uuid]';

-- S'assurer que is_static est false (true force un path buildkit incompatible)
UPDATE applications SET is_static = false WHERE uuid='[votre-uuid]';

-- Quitter psql
\q

10. Flow Directus → rebuild automatique

L’automatisation centrale de la stack : quand un gestionnaire modifie du contenu dans Directus, le site se reconstruit automatiquement en ~2-3 minutes.

Création du Flow

URL de déploiement Coolify

POST http://[IP-coolify-interne]:8080/api/v1/deploy?uuid=[UUID-APP]&force=true

# Exemple :
POST http://172.20.0.1:8080/api/v1/deploy?uuid=abc123def456&force=true

# Header :
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGci...

Trouver l’UUID de l’application

# Via l'interface Coolify :
# Application > Settings > l'UUID est dans l'URL et dans les infos générales

# Via l’API Coolify :
curl -H "Authorization: Bearer [token]" http://[IP]:8080/api/v1/applications
# Retourne la liste des applications avec leurs UUID

# Via la base de données Coolify :
docker exec -it coolify-db psql -U coolify -c "SELECT uuid, name FROM applications;"

Tester le Flow manuellement

# Tester l'appel API Coolify directement (depuis le VPS ou depuis Directus) :
curl -X POST \
  "http://172.20.0.1:8080/api/v1/deploy?uuid=abc123&force=true" \
  -H "Authorization: Bearer [votre-token]"

# Réponse attendue si tout est correct :
# {"message":"Deployment queued."}

11. Tableau des problèmes rencontrés et solutions

Tous les problèmes ci-dessous ont été rencontrés et résolus lors d’un déploiement réel de cette stack. Aucun n’est hypothétique.

12. Résumé des commandes utiles

Inspecter les containers Docker

# Lister tous les containers actifs
docker ps

# Lister tous les containers (y compris arrêtés)
docker ps -a

# Voir les réseaux Docker d’un container
docker inspect [nom-container] | grep -A20 '"Networks"'

# Voir l’IP d’un container
docker inspect [nom-container] | grep IPAddress

# Voir les variables d’environnement d’un container
docker inspect [nom-container] | grep -A50 '"Env"'

Logs de déploiement Coolify

# Logs temps réel du daemon Coolify
docker logs -f coolify

# Logs du container applicatif (site Astro/nginx)
docker logs -f [nom-container-app]

# Logs du container Directus
docker logs -f [nom-container-directus]

# Logs en temps réel avec filtre
docker logs -f [container] 2>&1 | grep -i "error\|warn\|build"

Accès à la base de données Coolify

# Entrer dans psql sur la base Coolify
docker exec -it coolify-db psql -U coolify

# Requetes utiles une fois connecté :
\dt                          -- lister toutes les tables
\d applications              -- structure de la table applications

-- Voir toutes les applications
SELECT uuid, name, build_pack, ports_exposes, start_command, is_static
FROM applications;

-- Corriger le port exposé
UPDATE applications SET ports_exposes = '80' WHERE uuid='[votre-uuid]';

-- Vider la commande de démarrage
UPDATE applications SET start_command = NULL WHERE uuid='[votre-uuid]';

-- Désactiver le mode static
UPDATE applications SET is_static = false WHERE uuid='[votre-uuid]';

-- Quitter
\q

Tester l’API Coolify

# Récupérer les informations du serveur
curl -H "Authorization: Bearer [token]" http://localhost:8080/api/v1/servers

# Lister les applications
curl -H "Authorization: Bearer [token]" http://localhost:8080/api/v1/applications

# Déclencher un déploiement manuellement
curl -X POST \
  -H "Authorization: Bearer [token]" \
  "http://localhost:8080/api/v1/deploy?uuid=[APP-UUID]&force=true"

# Vérifier les déploiements en cours
curl -H "Authorization: Bearer [token]" \
  "http://localhost:8080/api/v1/applications/[APP-UUID]/deployments"

Tester Directus depuis un autre container

# Lancer un container temporaire sur le réseau coolify pour tester l'accès Directus
docker run --rm --network coolify curlimages/curl \
  http://[IP-DIRECTUS]:8055/items/services

# Tester depuis le host (si Directus expose un port sur le host)
curl http://localhost:8055/items/services

# Tester avec authentification (si les permissions publiques ne sont pas activées)
curl -H "Authorization: Bearer [token-admin-directus]" \
  http://[IP-DIRECTUS]:8055/items/services

Gestion des réseaux Docker

# Lister tous les réseaux Docker
docker network ls

# Inspecter le réseau coolify
docker network inspect coolify

# Connecter un container à un réseau
docker network connect coolify [nom-container]

# Déconnecter un container d’un réseau
docker network disconnect coolify [nom-container]

Commandes build locales (test avant push)

# Builder l'image Docker localement
docker build -t mon-site-vitrine:test .

# Lancer le container pour tester
docker run -p 8080:80 mon-site-vitrine:test

# Accéder sur http://localhost:8080

# Nettoyer les images de test
docker rmi mon-site-vitrine:test

# Voir la taille de l'image finale
docker images mon-site-vitrine:test