Déployer Northstack

Trois façons de déployer

Quelle que soit la méthode choisie, le site et le tableau de bord compilent l'adresse de l'API dans leur JavaScript quand ils sont construits : construisez-les donc avec les adresses publiques, jamais les adresses locales.

Docker Compose sur un seul serveur

Copiez le dossier du pack sur le serveur et mettez un .env à côté de docker-compose.yml avec les trois adresses publiques. Les origines autorisées de l'API, les liens qu'elle écrit dans les invitations, les réinitialisations de mot de passe et les retours de paiement, les liens de téléchargement des factures, l'adresse des médias et l'adresse d'API des frontends en sont tous construits.

SITE_URL=https://www.your-domain.com
ADMIN_URL=https://app.your-domain.com
API_URL=https://api.your-domain.com

Puis construisez et démarrez en arrière-plan :

docker compose up --build -d

• Faites pointer chaque domaine vers le serveur via un reverse proxy qui sert le HTTPS (Caddy, Nginx ou Traefik), en redirigeant vers les ports 3030, 3031 et 8000.
• Copiez back-end/.env.example vers back-end/.env pour les clés de paiement, d'e-mail, de stockage, d'IA et de MCP : le conteneur de l'API le lit s'il existe, et docker-compose.yml garde les valeurs qui doivent différer dans un conteneur. Derrière le proxy, définissez-y TRUST_PROXY=1, pour que la limite de connexion compte chaque visiteur plutôt que le proxy.
• Sans JWT_SECRET à vous, l'API en génère un à son premier démarrage et le garde dans le volume northstack-data. La base et les fichiers téléversés vivent aussi dans ce volume : sauvegardez-le.
• Pour une vraie installation, démarrez le nouveau volume à vide : mettez SEED_SAMPLE_DATA=false dans le fichier .env à côté de docker-compose.yml (pas back-end/.env : Compose passe ces trois valeurs depuis celui-là), avec ADMIN_EMAIL et ADMIN_PASSWORD pour votre premier admin de la plateforme, avant le premier docker compose up. Le .env à côté de docker-compose.yml n'atteint pas l'API pour cela. Voir Démarrer à vide plus bas.
• Laissé à sa valeur par défaut (SEED_SAMPLE_DATA=true), le premier démarrage sur un nouveau volume initialise les espaces de travail d'exemple et leurs comptes, tous avec le mot de passe publié. Faites-les vôtres avant que la pile soit accessible, comme dans Partir des données d'exemple plus bas.

L'API à partir de son Dockerfile

Pointez l'hébergeur vers le dossier de l'API (back-end/ dans le Full Stack). L'image tourne avec NODE_ENV=production, écoute sur PORT (8000 sauf si l'hébergeur en définit un autre), répond à GET /api/health dès que sa base contient le schéma, et garde SQLite et les fichiers téléversés dans /data.

• Montez un volume persistant sur /data. Sans lui, chaque déploiement repart sur une nouvelle base.
• Définissez SEED_SAMPLE_DATA=false, avec ADMIN_EMAIL et ADMIN_PASSWORD, pour qu'un nouveau volume démarre avec votre propre admin de la plateforme et sans données d'exemple. Laissé à true, la valeur par défaut, un nouveau volume est initialisé avec les comptes d'exemple et leur mot de passe publié.
• Définissez CORS_ORIGIN avec les adresses du site et du tableau de bord (séparées par des virgules), FRONTEND_URL et DASHBOARD_URL avec celle du tableau de bord, WEBSITE_URL avec celle du site, PUBLIC_API_URL avec l'adresse publique de l'API et PUBLIC_MEDIA_URL avec cette adresse suivie de /media.
• Sur SQLite, un volume sans base est créé une seule fois, comme le dit SEED_SAMPLE_DATA ; une base existante n'est plus jamais initialisée et ses tables ne sont jamais modifiées au démarrage (voir Mise à jour plus bas).
• Définissez votre propre JWT_SECRET, ou laissez le conteneur en générer un et le garder dans /data/.jwt-secret.
• Définissez TRUST_PROXY=1 : une plateforme d'hébergement place un proxy devant le conteneur.
• Sur MySQL (DB_TYPE=mysql et les cinq variables DB_*), le conteneur ne crée pas les tables. Lancez une fois node dist/database/create-admin.js avec le même environnement (ou node dist/database/seeder.js pour une installation d'exemple).
• Les fichiers téléversés sur le volume survivent à un redéploiement ; pour ne pas les garder sur le serveur, définissez les cinq variables R2_* pour un bucket.

Le site et le tableau de bord à partir de leurs Dockerfiles

Faites pointer l'hébergeur vers le dossier de l'application et donnez-lui les valeurs NEXT_PUBLIC_* comme arguments de build, non comme variables d'exécution : elles sont compilées. Chaque image sert le serveur autonome de Next.js sur PORT (3030 pour le site, 3031 pour le tableau de bord, sauf si l'hébergeur en impose un autre).

Le serveur du site lit aussi l'API quand il rend le paiement et son reçu. Avec une adresse d'API publique qui fonctionne aussi depuis le serveur, rien d'autre n'est nécessaire ; API_INTERNAL_URL à l'exécution la remplace quand le serveur doit utiliser une autre adresse.

Node.js seul

Construisez chaque application une fois sur l'hôte, puis démarrez-la. Réglez le .env des frontends sur les adresses publiques avant yarn build.

L'API se lie à 0.0.0.0 et lit PORT. Gardez le fichier SQLite et MEDIA_UPLOAD_DIR sur un stockage qui survit à un déploiement, ou utilisez MySQL et un bucket. En production, l'API ne crée ni ne modifie jamais les tables seule : yarn admin:create:prod les crée avec votre premier admin de la plateforme, et yarn schema:prod les met à jour après une mise à jour.

Partir à vide, avec votre propre admin de la plateforme

Une vraie installation démarre sans données d'exemple et avec un seul compte, le vôtre. Dans le dossier de l'API, après yarn build :

yarn admin:create:prod

• Il crée les tables, les rôles et les paramètres de la plateforme, et le premier admin de la plateforme à partir de ADMIN_EMAIL et ADMIN_PASSWORD (8 à 128 caractères) dans l'environnement ou dans back-end/.env. Il demande dans le terminal celui des deux qui est vide, et ADMIN_NAME est facultatif.
• Il ne crée aucun espace de travail ni aucun compte d'exemple, et il refuse quand un admin de la plateforme existe déjà. Connectez-vous avec ce compte et créez votre espace de travail dans l'onboarding.
• yarn admin:create fait la même chose depuis les sources, sans build.
• Avec Docker, SEED_SAMPLE_DATA=false fait cela au premier démarrage : avec ADMIN_EMAIL et ADMIN_PASSWORD définis, il crée l'admin, et sans eux il crée seulement les tables et son journal indique la commande à lancer ensuite, docker compose exec -u node api node dist/database/create-admin.js (avec docker run, docker exec -it -u node <container> node dist/database/create-admin.js).

Mise à jour : les tables après une mise à jour

Il n'y a pas de migrations, et en production l'API ne modifie jamais les tables seule. Après une mise à jour dont le code change les tables, sauvegardez la base, construisez, et mettez les tables au niveau du nouveau code avant de démarrer l'API :

yarn build
yarn schema:prod
yarn start:prod

• yarn schema:prod n'écrit aucune donnée. Il ajoute ce qui est nouveau, et il supprime aussi, avec ses données, une colonne que le code n'a plus : la sauvegarde passe donc en premier.
• Avec Docker, un volume existant est laissé tel quel au démarrage. Une fois la nouvelle image lancée, appliquez le schéma dedans : docker compose exec -u node api node dist/database/schema.js (avec docker run, docker exec -u node <container> node dist/database/schema.js).

Partir des données d'exemple

Chaque seed crée les espaces de travail d'exemple et leurs personnes, les six connexions documentées et tous les autres comptes du seed, tous avec le même mot de passe publié, et l'image Docker initialise seule un nouveau volume sauf si SEED_SAMPLE_DATA=false. Si vous partez des données d'exemple, faites de l'installation la vôtre avant qu'elle soit accessible depuis Internet :

1. Faites vôtre l'admin de la plateforme du seed : connectez-vous avec platform@northstack.example, changez son nom et son e-mail dans Settings, Profile, et son mot de passe dans Settings, Security.
2. Pour votre propre espace de travail, inscrivez-vous sur le tableau de bord avec votre propre e-mail : l'onboarding crée l'espace, dont vous êtes le propriétaire. Ou faites vôtre le propriétaire du seed de la même façon et renommez Forma Studio dans Settings, General.
3. Sur la page Users de la plateforme, Delete les comptes d'exemple dont vous n'avez pas besoin, ou utilisez Change password sur ceux que vous gardez. Un compte qui possède un espace de travail est refusé tant qu'un autre membre n'en est pas propriétaire (depuis la page Team de cet espace) ou que l'espace n'est pas supprimé (ses Settings, Danger zone).
4. Définissez votre propre JWT_SECRET, pour qu'un jeton de connexion créé avant le changement cesse de fonctionner.

Un seed crée les comptes et les espaces de travail d'exemple uniquement dans une base qui n'a encore aucun compte. Dès que des comptes existent, relancer yarn seed ou yarn seed:prod n'ajoute ni compte ni espace de travail et redonne seulement leurs permissions aux rôles intégrés de la plateforme : un compte d'exemple que vous avez renommé ou supprimé ne revient donc jamais avec le mot de passe publié.

• Équipe et rôles
• Administration de la plateforme

Mise en ligne

Avant que Northstack soit accessible depuis Internet :

1. Dans l'environnement de l'API, NODE_ENV=production et un long JWT_SECRET aléatoire de votre choix (Docker en génère un quand aucun n'est défini). En production, l'API refuse de démarrer avec le secret d'exemple ou sans CORS_ORIGIN, et indique quelle valeur est fausse.
2. CORS_ORIGIN avec le site et le tableau de bord, FRONTEND_URL et DASHBOARD_URL avec le tableau de bord, WEBSITE_URL avec le site, PUBLIC_API_URL avec l'API et PUBLIC_MEDIA_URL avec l'API suivie de /media.
3. Votre clé Stripe live et son webhook sur /api/billing/webhooks/stripe à l'adresse de l'API, avec STRIPE_WEBHOOK_SECRET : sans lui, l'API le signale dans son journal au démarrage et refuse chaque envoi, si bien que les renouvellements et les paiements échoués ne sont jamais enregistrés. Pour PayPal, les clés de l'application live avec PAYPAL_ENV=live.
4. La fiscalité configurée pour votre pays : Northstack n'applique aucune taxe de lui-même.
5. Les paramètres SMTP_*, sinon personne ne reçoit les invitations, les réinitialisations de mot de passe ni les reçus de licence.
6. La base et les fichiers téléversés sur un stockage persistant, avec une sauvegarde.
7. La vérification de santé de l'hébergeur sur /api/health, et TRUST_PROXY=1 derrière un proxy.
8. Les deux frontends construits avec les valeurs publiques NEXT_PUBLIC_*.
9. Votre marque dans chaque frontend, et les pages légales du site réécrites pour votre activité et votre pays.
10. Aucun compte d'exemple : démarrage à vide avec yarn admin:create:prod ou SEED_SAMPLE_DATA=false, ou comptes du seed supprimés ou mots de passe changés, comme ci-dessus.
11. DEMO_MODE=false sur l'API et NEXT_PUBLIC_DEMO_MODE=false dans les deux frontends, comme livré.

• Variables d'environnement
• Image de marque