Local Install

Local Install (Development)

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

deploy/hotfix-local.ps1 owns the single localhost application: the native Meteor/Rspack source watcher at http://localhost:3200. Docker Compose supplies 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 and the existing MoFaCTS checkout
• Docker Desktop with Compose
• Node.js 24.15.0 and npm 11.12.1, pinned in mofacts/package.json
• The pinned Meteor tool matching mofacts/.meteor/release, currently METEOR@3.5
• Windows for the supported supervisor, which owns its process tree with Windows Job Objects

From the application's mofacts/ directory, install locked dependencies with npm ci. Meteor UI, persistence, and server integration belong in mofacts/; pedagogical engines and models belong in learning-components/. See Developer Reference for the source map.

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 must supply MOFACTS_NATIVE_MONGO_URL using the host-accessible MongoDB address and configured replica-set identity. The container address mongodb:27017 is not the native host connection. Keep the canonical database name 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.

Start and manage the watcher

From deploy/:

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

Open http://localhost:3200. The launcher owns the supervisor, Meteor process, and Rspack 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. Failure logs are retained under ignored deploy/local-hotfix/runs/; status reports 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 watcher manager owns a durable supervisor and its complete Meteor/Rspack process tree. Status checks validate PID identity and report readiness and the last recognized failure. Previous logs are archived under ignored deploy/local-hotfix/runs/; generated output is rebuilt by the watcher. A bounded startup retry follows repeated database-primary readiness checks, and recurring failures remain visible.

From the application's mofacts/ directory:

npm run typecheck
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

Symptom	Check
Missing settings or native MongoDB URL	Review .env.local and its existing private settings path.
MongoDB not ready	Inspect authenticated access and the configured replica-set primary; do not substitute another database.
Port occupied	Use launcher status to identify ownership and preserve unrelated listeners.
Source edits do not rebuild	Inspect watcher and Rspack status/logs; do not patch compiled output.
Wrong tool version	Match package.json and .meteor/release.
Microphone fails on another device	Verify the HTTPS host, certificate trust, permissions, and network route.

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.