Démarrage rapide

Vérifié avec le commit e632762.

Commencez par Core : l’app client, le worker durable, PostgreSQL, Redis et le stockage local privé. Le premier objectif est un parcours local complet : connexion, attribution de crédits démo, tâche image simulée, résultat privé et écriture au registre. Aucun compte Stripe, email ou fournisseur d’IA n’est nécessaire pour ce parcours local.

Choisir votre point de départ

Vous pourrez ajouter les autres applications plus tard. Les profils sélectionnent des outils et cibles de build, sans changer les forfaits, les permissions ou les routes API disponibles.

1. Préparer votre machine

• Git
• Node.js >=24.22.1 <25 (.nvmrc indique la version testée)
• pnpm 10.22.0
• Docker avec Compose, démarré en local

2. Lancer Core

Exécutez ces commandes dans un terminal. La branche part de la révision vérifiée pour garder le code et les instructions alignés.

git clone https://github.com/PansaLegrand/sushi-saas-template.git
cd sushi-saas-template
git switch -c my-saas e63276252e4b64566229cb87225afc72da6991de
export SAAS_STARTER_PROFILE=core
pnpm starter core install
pnpm starter core setup
pnpm starter core doctor
pnpm starter core demo

demo exécute d’abord doctor en lecture seule, prépare le compte local uniquement après sa réussite, puis démarre Core avec les images simulées, zéro échec fournisseur simulé et le captcha local désactivé. Email, Slack et Stripe sont désactivés pour ces processus ; les fichiers d’environnement restent inchangés. Aucun fournisseur IA commercial n’est contacté. Utilisez bash/zsh ou WSL. pnpm starter core dev reste le parcours de développement habituel et n’active pas ce mode démo.

Laissez le terminal ouvert, puis rendez-vous sur localhost:3000/fr/login.

Setup crée les fichiers d’environnement ignorés manquants, démarre PostgreSQL, Redis et Garage, crée les bases locales app/test et de restauration, applique les migrations Drizzle et prépare le bucket privé sushi-dev. Core omet l’installation, les fichiers d’environnement, la base et les migrations de Content Studio. Vous pouvez relancer setup : il ne remplace jamais un fichier d’environnement existant.

Avant d’écrire les fichiers d’environnement, setup vérifie Docker actif, Docker Compose et l’appartenance des services sur les ports 5432/6379. Un outil absent, Docker arrêté ou un service en conflit provoque un arrêt en erreur ; corrigez le prérequis indiqué avant de réessayer.

doctor vérifie en lecture seule outils, limites d’environnement, infrastructure, migrations, stockage et ports sans afficher les secrets. Demo vérifie doctor avant le seed, puis lance web et worker sans répéter inutilement cette vérification. Ctrl-C arrête les deux processus.

Exportez SAAS_STARTER_PROFILE=core dans chaque terminal utilisé pour pnpm lint ou les commits après l’installation filtrée. Ces commandes export utilisent un shell POSIX ; sous PowerShell, utilisez $env:SAAS_STARTER_PROFILE="core".

3. Obtenir votre premier écran fonctionnel

1. Pour un nouveau compte, utilisez demo@example.test et DemoPass123!, ou le DEV_SEED_PASSWORD utilisé lors de sa création. Un compte existant conserve son mot de passe initial ; la sortie de demo indique qu’il est inchangé.
2. Ouvrez Compte → Crédits. Repérez l’attribution démo unique de 1 000 crédits. Le worker peut aussi traiter l’attribution d’inscription distincte de 10 crédits, portant un solde neuf à 1 010. L’attribution démo ne signifie pas que le solde total reste toujours à 1 000.
3. Ouvrez Compte → Profil et sécurité pour explorer les réglages. Votre espace et votre session utilisent maintenant la véritable application locale.

Ces identifiants sont réservés au développement local. Le seed crée un compte vérifié avec domaine réservé et répare les fixtures sans attribuer deux fois le même crédit. Aucun email n’a besoin d’être envoyé. Une activité démo existante peut modifier le solde affiché.

4. Réussir votre première tâche image

1. Une fois les attributions initiales traitées, actualisez Compte → Crédits et notez le solde. Gardez le même espace pendant tout le parcours.
2. Ouvrez la tâche image locale. Conservez le paramètre org ajouté à l’URL. Saisissez Ma première tâche image Sushi SaaS dans Instruction, puis cliquez une seule fois sur Générer l’image.
3. L’état peut passer brièvement par En attente du worker… puis Génération et stockage de l’image…. Attendez Image prête. Le résultat attendu est un SVG bleu/violet marqué Image generation mock, avec votre instruction. C’est une réponse simulée, pas une illustration créée par IA.
4. Actualisez la même URL : vous devez retrouver le même ID de tâche et l’image sans nouveau débit. Générer une autre image crée volontairement une nouvelle tâche, facturée cinq crédits supplémentaires.
5. Dans Compte → Crédits, pour le même espace, repérez un seul débit Génération d’image de −5. Sans autre écriture, le solde est celui noté moins cinq : 1 000 → 995, ou 1 010 → 1 005 après l’attribution d’inscription. Dans Compte → Fichiers, le résultat s’appelle generated-<ID de tâche>.svg.

Le résultat est stocké dans le bucket Garage local privé. La page l’affiche avec une URL signée valable 15 minutes ; rouvrir l’URL de la tâche en crée une nouvelle. L’URL signée donne elle-même un accès temporaire à son détenteur : ce n’est pas une adresse publique permanente.

Vous avez testé : connexion → autorisation de l’espace → débit unique de cinq crédits → worker durable → résultat privé → reprise dans l’interface. Le forfait Free inclut cet exemple ; aucun abonnement ni seed --paid-examples n’est nécessaire.

Si le premier essai bloque

Vérifier la stack locale

Dans un autre terminal, vérifiez les services :

curl http://localhost:3000/api/health
curl http://localhost:3000/api/ready
pnpm test:fast

Arrêtez le lanceur avec Ctrl-C avant de compiler : les modes développement et production partagent .next.

pnpm starter core build

Le build conserve la suite de tests racine et prépare le runtime du worker. Pour les parcours navigateur avec stockage local réel et jobs simulés dans un environnement jetable, consultez Tests et CI.

5. Personnaliser votre produit

Exécutez pnpm customize pour définir identité, apparence et langues. Continuez avec Personnalisation et Architecture. Configurez les services externes lorsque la fonctionnalité choisie le nécessite : Configuration d’environnement.

Ajouter des applications au besoin

Arrêtez le lanceur actuel avant de changer de profil. Pour ajouter l’admin sur http://localhost:3001 :

export SAAS_STARTER_PROFILE=operations
pnpm starter operations install
pnpm starter operations setup
pnpm starter operations dev

Suivez Configurer la console admin pour les accès opérateur et le MFA ; le compte client démo n’est pas automatiquement administrateur.

Pour ajouter également Content Studio sur http://localhost:3002/admin :

export SAAS_STARTER_PROFILE=publishing
pnpm starter publishing install
pnpm starter publishing setup
pnpm starter publishing dev

Publishing prépare la base Payload et ses migrations séparées. Conservez une authentification et une base distinctes du SaaS ; voir Content Studio et marketing.

Tous les profils proposent doctor, lint, build et --dry-run. Sans profil sélectionné, pnpm run setup, pnpm dev:all et pnpm build gardent la stack complète. Pour le customizer interactif complet, utilisez ./scripts/setup.sh development sans SAAS_STARTER_PROFILE dans le shell.

Réinitialiser les données locales volontairement

pnpm dev:reset -- --dry-run
pnpm dev:reset

Prévisualisez d’abord les cibles. Reset refuse les services externes, exige une confirmation, ne recrée que les données de ce projet Compose, réapplique les migrations et relance le seed sauf indication contraire. Il conserve les profils d’environnement. Un redémarrage normal ne nécessite pas de reset.