# 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](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](Remote-Install); image deployment, Apache/TLS, and explicit cutover |
| Configure authentication, mail, and providers | [Settings Reference](Settings-json-Reference) and private env files |
| Maintain backups and inspect security evidence | [Admin Reference](Admin-Reference), [Security Audit Operations](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:

```bash
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](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](Remote-Install) for the detailed Apache/TLS and Elastic IP sequence, and the repository's deployment scripts for backup/restore and runtime maintenance.