Déploiement fr FR

Résumé : Cette section présente les différentes manières de déployer une application StartER, en environnement de développement ou de production.

L'architecture isomorphe

StartER repose sur une architecture isomorphe (frontend et backend intégrés), ce qui simplifie la configuration : une seule commande permet de construire et de lancer l'ensemble du projet.

Implémentation dans StartER

Environnement local

Mode développement

En mode développement, le serveur est lancé avec Vite configuré en middleware mode. Cela permet de bénéficier du rechargement à chaud, d'un rendu serveur (SSR) dynamique, et d'une compilation à la volée.

Commencez par initialiser votre base de données locale si ce n'est pas déjà fait :

npm run database:sync

Ensuite, lancez le serveur :

npm run dev

Le serveur Express est alors accessible sur l'adresse : http://localhost:5173. Ce mode utilise les sources brutes (TypeScript, JSX...) sans passer par un processus de build.

Mode production locale

Pour simuler un environnement de production sans Docker, lancez la séquence de build puis d'exécuter le serveur compilé :

npm run build
npm start

La commande npm run build exécute successivement :

vite build --outDir dist/client pour compiler la partie cliente (frontend)
vite build --outDir dist/server --ssr src/entry-server pour compiler la partie serveur (SSR)

Quand NODE_ENV=production dans les variables d'environnement, le serveur Express (server.ts) détecte automatiquement le mode production et :

active la compression des réponses HTTP
sert les fichiers statiques précompilés depuis dist/client
utilise le rendu serveur depuis dist/server/entry-server

Utiliser avec Docker Compose

StartER adopte une approche "Zéro-Config". Docker n'est pas nécessaire pour faire fonctionner la base de données (SQLite), mais reste fourni pour des outils optionnels comme Mailpit.

Environnement de développement

En développement, Docker lance uniquement le service suivant si vous le souhaitez :

mailpit : un serveur SMTP fictif pour intercepter et visualiser les emails envoyés par l'application.

Pour démarrer Mailpit :

docker compose up --build

L'interface de Mailpit sera accessible sur http://localhost:8025.

Environnement de production

Pour un déploiement conteneurisé en production, StartER fournit un fichier compose.prod.yaml. Le conteneur server construit le projet à l'intérieur de l'image avant de le lancer.

Pour déployer en production :

docker compose -f compose.prod.yaml up --build

Le build client et serveur sera généré dans dist/, et le serveur Express servira directement les fichiers optimisés.

Base de données et persistance

Puisque StartER utilise SQLite, la base de données est un simple fichier situé dans src/database/data/database.sqlite.

Pour conserver vos données lors d'un déploiement avec Docker, vous devez utiliser un volume qui pointe vers le répertoire des données :

# Exemple simplifié de compose.prod.yaml
services:
  server:
    # ... configuration du serveur ...
    volumes:
      - ./src/database/data:/app/src/database/data

Ainsi, même si vous recréez le conteneur, le fichier SQLite restera intact sur votre machine hôte.

Variables d'environnement

Les variables nécessaires au fonctionnement de StartER sont définies dans le fichier .env. Contrairement aux systèmes de bases de données relationnelles traditionnelles (MySQL, Postgres...), il n'y a aucune variable de connexion réseau à configurer pour SQLite.

# .env - Environment Variables Configuration

# The base URL where your application is accessible (used for magic links)
APP_BASE_URL=http://localhost:5173

# The port on which the Express server will listen (default: 5173)
APP_PORT=5173

# Secret key used for signing JWTs and other security features.
# TIP: You can use `openssl rand -hex 32` to generate a secure random key.
APP_SECRET=YOUR_APP_SECRET_KEY

# The SMTP connection URL used by the application to send emails.
SMTP_URL=smtps://username:password@smtp.example.com/?pool=true

Déploiement avec Caddy

Caddy est un excellent reverse proxy qui gère automatiquement les certificats HTTPS. Il permet de rendre votre application StartER accessible sur le web très simplement.

Exemple de configuration (`Caddyfile`)

mon-domaine.com {
  reverse_proxy localhost:5173
}

Lancez StartER (via Docker ou npm start).
Lancez Caddy avec cette configuration.
Votre application est disponible en HTTPS sur https://mon-domaine.com.

Bonnes pratiques et cas d'usage

Ne commitez jamais le fichier .env ou le fichier database.sqlite (ils sont exclus par défaut dans le .gitignore).
En production, utilisez toujours une clé APP_SECRET forte et unique.
Assurez-vous que le dossier src/database/data possède les droits d'écriture pour l'utilisateur qui lance le serveur.