Local Install (Development)

Last Updated: 2026-10-29 | For: Developers and local verification

deploy/hotfix-local.ps1 owns the single localhost application: the Linux Docker Meteor/Rspack source watcher at http://localhost:3200. Docker Compose owns the watcher, MongoDB and replica-set initialization. Source edits rebuild and reload automatically.

On this page

• Prerequisites
• Private local configuration
• Start and manage the watcher
• Local HTTPS
• Verification
• Troubleshooting

Prerequisites

• Git, PowerShell and the existing MoFaCTS checkout
• Docker Desktop using Linux containers, with Compose 2.24.4 or newer

The container provides Meteor 3.5.4, Node 24.22.1 and npm 11.19.1. No host Meteor installation is required. Locked dependencies and generated caches live in Linux Docker volumes. Application integration belongs in mofacts/; pedagogical engines and models belong in learning-components/.

Private local configuration

From the repository's deploy/ directory, create private files from templates for a new setup:

Copy-Item .env.local.example .env.local
Copy-Item settings.local.example.json settings.local.json

If private files already exist, review them in place; do not replace working configuration with templates. Replace placeholders before startup and keep credentials out of commits.

METEOR_SETTINGS_HOST_PATH must identify an existing private settings file with the configured owner for local administrator bootstrap. .env.local supplies MONGO_URL using mongodb:27017 and the configured replica-set identity. Keep the database and replica-set configuration consistent with the launcher.

The private MongoDB member keyfile must exist at MONGO_REPLICA_SET_KEYFILE_HOST_PATH. For initial local setup use:

.\New-MongoReplicaSetKeyfile.ps1

Converting an existing standalone database requires the documented maintenance procedure and a restorable backup. Starting from templates is not authorization to reinitialize a database. The launcher validates configuration and database readiness before starting Meteor.

After primary election, the initializer ensures the application account has the mofactsReadDefaultConcern role. It permits only getDefaultRWConcern, the read-only command Meteor uses to inspect consistency defaults. Existing database roles are preserved; learner records and passwords are not changed. The step is restartable for new and existing installations and rejects a conflicting role definition. See the repository deployment guide's Security Notes for rollback.

Start and manage the watcher

From deploy/:

.\hotfix-local.ps1 -Action start
.\hotfix-local.ps1 -Action status

Open http://localhost:3200. Compose owns the Linux Meteor/Rspack container and its descendants. Use the same owner for lifecycle actions:

.\hotfix-local.ps1 -Action logs -LogTail 120
.\hotfix-local.ps1 -Action restart
.\hotfix-local.ps1 -Action stop

Ordinary source edits do not require a restart. Use restart for changes that require a new process or after diagnosing a failed development run. Stop manages the application process tree; it does not delete database volumes or learner data.

Do not start a second native or containerized localhost application, patch generated bundles, or replace source watching with a manual build loop. Docker retains bounded logs; status reports container ownership and readiness.

Local HTTPS

The HTTPS helper puts Caddy in front of the same watcher. Set MOFACTS_CADDY_EXE to an existing executable:

$env:MOFACTS_CADDY_EXE = 'C:\Path\To\caddy.exe'
.\start-lan-https.ps1

The tracked Caddyfile.local serves https://localhost:3000 and proxies to 127.0.0.1:3200. Its configured hostname is localhost. Access from another device requires a deliberately configured hostname or address, suitable certificate trust, and network access; the helper's name does not make localhost a phone-accessible endpoint.

For a configuration using Caddy's internal certificate authority, clients must trust that authority. On Windows its usual root-certificate location is C:\Users\<user>\AppData\Roaming\Caddy\pki\authorities\local\root.crt. On iPhone, install the profile, then enable full trust under Settings → General → About → Certificate Trust Settings. Verify the actual host and certificate when diagnosing microphone access.

Use the paired stop helper when finished:

.\stop-lan-https.ps1

Verification

The manager checks stable MongoDB primary/authentication readiness, app health, browser bundle, HMR and active Change Streams. Docker owns process lifetime and bounded logs. Startup failures remain visible without an automatic restart loop.

From deploy/, run checks inside the managed Linux container:

docker compose --env-file .env.local -f docker-compose.yml -f docker-compose.local.yml exec -T mofacts meteor npm run typecheck
docker compose --env-file .env.local -f docker-compose.yml -f docker-compose.local.yml exec -T mofacts meteor npm run lint

Run the full app typecheck for TypeScript changes and lint for lintable TypeScript, JavaScript, or Svelte changes. Schema changes also require npm run generate:schemas and inspection of generated diffs. Required failures must be resolved or explicitly accepted before staging, committing, or pushing.

Meteor integration tests need CI or another supported Meteor environment. Each npm run test:ci invocation requires fresh, explicit authorization for agent work; it is not a routine local Windows check. The watcher establishes local verification. Release confidence uses the canonical Docker Compose image workflow with separate authorization for builds, pushes, and deployments.

Stay on the current branch unless a branch change is requested. Review intentional files before staging; commits and pushes require explicit instructions. Pre-commit hooks check staged lint and secrets.

Troubleshooting

Process ownership and readiness details live in the repository's deploy/hotfix/README.md. Server operation is covered in Remote Install; runtime configuration is covered in Settings.json Reference.