Deployment Guide
Last Updated: 2026-10-09 | For: System administrators and developers
MoFaCTS uses the root deploy/ Docker Compose workflow for image builds and deployment. The application is pinned to Meteor 3.5, Node 24.15.0, and npm 11.12.1. Runtime configuration is private and mounted separately from the image.
Choose a workflow
| Purpose | Guide and owner |
|---|---|
| Edit source and observe local rebuilds | Local Install; deploy/hotfix-local.ps1 owns one native Meteor/Rspack watcher at port 3200, while Compose owns MongoDB |
| Build or qualify an application image | Root Dockerfile, deploy/docker-compose.yml, and CI |
| Install a server or switch AWS traffic | Remote Install; image deployment, Apache/TLS, and explicit cutover |
| Configure authentication, mail, and providers | Settings Reference and private env files |
| Maintain backups and inspect security evidence | Admin Reference, Security Audit Operations, and deploy/README.md |
Runtime contract
The canonical Compose stack contains the app, authenticated MongoDB, a one-time replica-set initializer, and authenticated Redis. MongoDB uses database MoFACT-meteor3 and replica set mofacts-rs. A single-member replica set supplies the required database behavior; it does not supply high availability. The app waits for database, replica initialization, and Redis health.
Compose fixes Meteor reactivity to changeStreams and DDP transport to sockjs. Use the supported runtime contract rather than an older polling environment example. MongoDB and Redis are internal services. Bind the app to loopback when a host reverse proxy owns public HTTP/HTTPS.
The server validates the replica-set connection and strict Change Streams driver before serving application traffic. Polling-only configuration or a polling observer is a runtime-contract error. Deployment readiness reports this boundary; do not reconfigure to polling to bypass a failure.
METEOR_SETTINGS_HOST_PATH selects the private settings file, mounted read-only at /run/mofacts/settings.json. METEOR_SETTINGS_FILE tells the entrypoint where to read it. Private env and backup directories have separate mounts. Keep the encryption key, database credentials, and replica keyfile in the recovery plan. Do not put them in an image or public repository.
Prepare configuration
Start from deploy/.env.self-hosted.example and deploy/settings.self-hosted.example.json. Replace placeholders, select the exact image tag/revision, configure an authenticated app-user MONGO_URL with the database and replica-set parameters, and set the private mount paths. Do not substitute the local env template for the production configuration.
For an existing database, stop writers, verify a restorable backup, and use the documented standalone-to-replica-set maintenance procedure. Reusing a volume is not evidence that credentials, replica state, or indexes are correct. Review existing-data recovery separately from empty-install startup.
Build and image verification
The following commands are for an explicitly authorized build/release operation. Run from root deploy/ after preparing private configuration:
docker compose --env-file .env.self-hosted -f docker-compose.yml build mofacts
docker compose --env-file .env.self-hosted -f docker-compose.yml push mofacts
Use an immutable release reference and retain the prior reference for rollback. Build completion, container health, and functional readiness are separate checks. Inspect /health, the deployed revision, reverse-proxy HTTP and WebSocket behavior, configured authentication/mail, content upload/launch, and deployment readiness before traffic cutover. The server deployment validator supports an explicit required readiness command; see deploy/server-deploy-validate.sh.
The local watcher is local verification. It does not establish image compatibility, successful staging delivery, production deployment, or release acceptance. A recorded staging result applies only to its revision, environment, and checks; partial acceptance retains its stated limits.
The repository's docs-developer/meteor-3.5-production-cutover-steps-4-13.md records the August 5, 2026 cutover and its maintenance/continuity checks. That dated record explains the transition; use current Compose and validation owners for a new operation rather than treating its past results as a check of today's host.
Troubleshooting and operation
Use Troubleshooting for settings, database, proxy, and startup symptoms. Read readiness errors at the owning boundary rather than changing database names or runtime modes to bypass validation. Use Remote Install for the detailed Apache/TLS and Elastic IP sequence, and the repository's deployment scripts for backup/restore and runtime maintenance.