Déploiement
Build de production, Docker, BoxLang MiniServer, et une checklist de mise en production.
Sur cette page
Déploiement
Build de production
npm run build
Compile et signe (fingerprint) le frontend dans public/includes/ - voir Frontend.
Docker
Un Dockerfile et des fichiers Compose spécifiques à chaque base de données vivent dans resources/docker/. MySQL est la valeur par défaut ; des alternatives PostgreSQL et MSSQL sont fournies pour les autres cibles testées en CI. MariaDB peut utiliser la configuration MySQL et le pilote JDBC mysql. box.json définit aussi les scripts docker:build, docker:run, docker:bash, et docker:stack (à exécuter avec box run-script <name>) comme raccourcis pour les commandes à argument unique ci-dessous - ils ne remplacent pas l'installation requise du CLI BoxLang pour les commandes box locales, et n'ont aucun rapport avec npm run (il n'existe pas de npm run docker:*).
Développement local avec Docker Compose
resources/docker/docker-compose.yml exécute l'application (construite à partir de resources/docker/Dockerfile.dev, qui installe CommandBox nativement par-dessus l'image officielle ortussolutions/boxlang:cli afin que la version du moteur corresponde à .bvmrc) aux côtés d'un conteneur MySQL 8, avec tout le dépôt monté en bind dans le conteneur applicatif afin que les modifications faites sur l'hôte s'appliquent sans reconstruction - aucune installation locale de BoxLang/MySQL n'est nécessaire. Exécutez docker compose directement (plutôt que via le script de package docker:stack) afin que les commandes à plusieurs mots comme up -d soient correctement transmises :
npm install
npm run build
docker compose -f resources/docker/docker-compose.yml up -d
docker compose -f resources/docker/docker-compose.yml exec coldbox_app box install
docker compose -f resources/docker/docker-compose.yml exec coldbox_app box migrate up
docker compose -f resources/docker/docker-compose.yml exec coldbox_app box migrate seed run
Visitez http://127.0.0.1:8080. MySQL est accessible depuis l'hôte sur 127.0.0.1:3406 (choisi pour éviter tout conflit avec un MySQL/MariaDB déjà en cours d'exécution sur 3306) ; le conteneur applicatif s'adresse à lui via le réseau Docker interne, sur le vrai port de MySQL, 3306.
Le fichier compose n'exécute pas Vite - démarrez-le séparément sur l'hôte pour le HMR :
npm install
npm run dev
Un fichier Compose spécifique à MSSQL est également disponible pour tester contre SQL Server 2022. Il installe le pilote bx-mssql dans le conteneur applicatif, crée la base de données cbgenesis, et conserve ses données sous resources/docker/.db/mssql/ :
npm install
npm run build
docker compose -f resources/docker/docker-compose.mssql.yml up -d
docker compose -f resources/docker/docker-compose.mssql.yml exec coldbox_app box install
docker compose -f resources/docker/docker-compose.mssql.yml exec coldbox_app box migrate up
docker compose -f resources/docker/docker-compose.mssql.yml exec coldbox_app box migrate seed run
L'application reste disponible sur http://127.0.0.1:8080 ; SQL Server est accessible depuis l'hôte sur 127.0.0.1:1434. Le mot de passe sa par défaut est prévu uniquement pour les tests locaux. Définissez MSSQL_SA_PASSWORD avant de démarrer la pile pour le remplacer. Arrêtez cette pile avec :
docker compose -f resources/docker/docker-compose.mssql.yml down
L'alternative PostgreSQL utilise PostgreSQL 16, publie le port hôte 5433, et installe automatiquement bx-postgresql :
npm install
npm run build
docker compose -f resources/docker/docker-compose.postgresql.yml up -d
docker compose -f resources/docker/docker-compose.postgresql.yml exec coldbox_app box install
docker compose -f resources/docker/docker-compose.postgresql.yml exec coldbox_app box migrate up
docker compose -f resources/docker/docker-compose.postgresql.yml exec coldbox_app box migrate seed run
Le fichier Compose MySQL par défaut reste inchangé. Arrêtez l'une ou l'autre alternative avec son fichier Compose correspondant et down.
docker compose -f resources/docker/docker-compose.yml down
Image de production
box run-script docker:build
box run-script docker:run
Construisez le frontend avant de créer une image de production :
npm run build
BoxLang MiniServer
Une alternative au serveur de développement bx-cli pour exécuter directement l'application compilée :
cd my-app
boxlang-miniserver --port 8080 --webroot ./public --dev
Le MiniServer ne fournit pas box install, les migrations, ni les commandes TestBox. Utilisez le CLI BoxLang requis pour ces tâches.
Checklist de mise en production
ENVIRONMENT=production et BOXLANG_DEBUG=false dans .env.
Pointez app/config/modules/cbmailservices.bx vers un vrai pilote SMTP/Postmark/SendGrid - voir Email.
Le seeder crée admin@cbgenesis.com / test, marqué comme en attente de réinitialisation. Se connecter avec ne donne pas de session : vous êtes envoyé directement vers le formulaire de réinitialisation de mot de passe et devez d'abord en définir un nouveau. Le hash de démarrage est public (il est livré dans le dépôt), donc ne retirez jamais ce marqueur pour continuer à utiliser test. Voir Démarrage.
reinitPassword lit COLDBOX_REINIT_PASSWORD depuis l'environnement. Laissez-le non défini en production et chaque démarrage se rabat sur un UUID aléatoire frais que personne ne connaît, ce qui ferme entièrement ?fwreinit. Ne le définissez que si vous devez réinitialiser une instance en cours d'exécution, et traitez-le comme un identifiant sensible. Le définir avec une chaîne vide laisse la réinitialisation ouverte à tout le monde, ce que fait précisément development(), et ce que la production ne doit pas faire.
Via la configuration SSL dans server.json, ou votre proxy inverse / répartiteur de charge de choix.
cbTrustProxyHeaders est activé par défaut, ce qui correspond à un déploiement typique derrière un proxy inverse ou un répartiteur de charge. Si l'application est directement exposée sur Internet, désactivez-le - voir Déployer derrière un proxy inverse. Se tromper dans ce sens désactive soit la limitation de débit, soit la casse pour tout le monde derrière le proxy.
app/config/modules/cbsecurity-passkeys.bx est livré avec des valeurs de substitution réservées au développement (relyingPartyId: "localhost", allowedOrigins: ["http://localhost:8080"]). Réglez-les sur votre véritable domaine de production avant la mise en ligne, sinon l'enregistrement des passkeys échouera - voir Sécurité & Permissions.
npm run build pour des assets minifiés et signés (fingerprintés).
Retirez ou restreignez le point de terminaison public /healthcheck s'il ne doit pas être accessible depuis l'extérieur de votre infrastructure.
Déployer derrière un proxy inverse
RateLimiter, le journal d'audit, et les emails de sécurité « réinitialisation demandée depuis l'IP » lisent tous l'IP de l'appelant via getRealIP() de cbsecurity. Cette fonction dispose de deux sources possibles pour l'IP, et seul vous - la personne qui déploie cette application - savez laquelle est correcte pour votre configuration :
- L'adresse brute du socket (
cgi.remote_addr) - correcte lorsque l'application est directement exposée sur Internet. Si un proxy inverse se trouve devant, il s'agit toujours de l'adresse du proxy lui-même, pas de celle du visiteur. - Les en-têtes de requête
X-Forwarded-For/X-Cluster-Client-IP- correctes uniquement lorsque quelque chose devant l'application (nginx, un répartiteur de charge, un CDN) supprime toute valeur envoyée par le client et définit lui-même l'en-tête. Si rien ne fait cela, n'importe quel appelant peut définir cet en-tête à n'importe quelle valeur, y compris une valeur différente à chaque requête.
Le paramètre cbTrustProxyHeaders (par défaut true, modifiable sur /settings) choisit entre les deux. Le laisser activé alors que vous n'êtes pas réellement derrière un proxy qui assainit l'en-tête rouvre exactement le contournement de limitation de débit qu'il est censé fermer - un appelant peut forger une nouvelle valeur X-Forwarded-For à chaque tentative de connexion et n'être jamais bloqué. Le désactiver alors que vous êtes derrière un tel proxy fait que chaque visiteur partage l'IP du proxy - un appelant bloqué bloque tout le monde derrière lui, et le journal d'audit enregistre l'adresse du proxy pour chaque action.
Si vous déployez directement exposé sur Internet, sans rien devant l'application, désactivez ce paramètre. Si vous déployez derrière un proxy inverse, confirmez qu'il écrase effectivement X-Forwarded-For (plutôt que d'ajouter à une valeur fournie par le client ou de la laisser passer) avant de laisser ce paramètre activé.