Settings.json Reference

Last Updated: 2026-10-09 | For: Administrators and developers

This page describes runtime settings.json used by Meteor/MoFaCTS.

Primary implementation owners are mofacts/server/lib/openCoreSettingsValidation.ts, deploy/docker/entrypoint.sh, and deploy/docker-compose.yml.

Where settings are used

Compose mounts the private host file named by METEOR_SETTINGS_HOST_PATH read-only at /run/mofacts/settings.json. The container entrypoint reads METEOR_SETTINGS_FILE and supplies its JSON to Meteor. Settings and credentials are not baked into the image. The local watcher receives an explicit -SettingsPath; see Local Install.

Quick Start

1. Work from the repository's root deploy/ directory.
2. Copy the appropriate settings.local.example.json or settings.self-hosted.example.json to a private file and replace placeholders.
3. Set METEOR_SETTINGS_HOST_PATH in the matching private env file. Keep the file and its encryption key available for recovery.
4. Match settings ROOT_URL to the env file and deployed endpoint. Required authentication settings must be explicit booleans.
5. Use the deployment readiness checks before opening the site to users. Template JSON is authoring material, not a verified working configuration.

Top-Level Fields

initRoles Object

auth Object

public Object (Client-Visible)

Everything in public is readable by clients.

Interface locale selection uses the explicit user preference first, then institution locale, deployment locale, permitted browser preferences, and the application locale (English). public.uiLocale sets the deployment locale; public.institutionLocale sets its institution preference; public.allowBrowserUiLocale = true permits browser language selection. Unsupported explicit values fail clearly. This controls platform labels, not lesson translation or response language. The locale catalog and review status live in mofacts/common/lib/interfaceLocales.ts.

OAuth Objects

google

• google.clientId (required if enabled)
• google.secret (required if enabled)

microsoft

• microsoft.clientId (required if enabled)
• microsoft.secret (required if enabled)

Production Template

Replace all sample identities, URLs, mail credentials, and the encryption-key placeholder. Startup rejects missing required fields and placeholders; this example cannot be deployed unchanged.

{
  "owner": "admin@yourdomain.edu",
  "ROOT_URL": "https://mofacts.yourdomain.edu",
  "encryptionKey": "REPLACE_WITH_RANDOM_BASE64",
  "prod": true,
  "enableEmail": true,
  "auth": {
    "allowPublicSignup": false,
    "requireEmailVerification": true,
    "enableBreachedPasswordScreening": true,
    "argon2Enabled": false
  },
  "initRoles": {
    "admins": ["admin@yourdomain.edu"],
    "teachers": []
  },
  "MAIL_URL": "smtp://user:password@mailhost:587",
  "public": {
    "systemName": "Research Learning Lab",
    "forceSSL": true,
    "admin": "admin@yourdomain.edu",
    "enableDeleteAllButton": false,
    "testLogin": false,
    "packages": { "accounts": { "clientStorage": "session" } }
  }
}

Validation Checklist

1. ROOT_URL exactly matches deployed HTTPS domain.
2. public.forceSSL is true in production.
3. owner and initRoles.admins refer to real accounts/emails.
4. encryptionKey is high entropy and documented for disaster recovery.
5. MAIL_URL tested (password reset email succeeds).
6. Verification email delivery succeeds for a test signup.
7. Breached-password screening can reach the HIBP range API from the deployment network.
8. auth.argon2Enabled is an intentional choice for this deployment and matches capacity planning.
9. The private settings file selected by METEOR_SETTINGS_HOST_PATH is excluded from git and restricted by filesystem permissions.
10. The administrator has completed and published Theme → Branding and Landing Page before the deployment URL is shared.

Auth Notes

Password Hashing

• MoFaCTS uses Meteor accounts-password for password hashing.
• Native password signup and reset currently require a minimum length of 8 characters.
• The runtime is explicitly configured with auth.argon2Enabled.
• false means bcrypt compatibility mode.
• true means Meteor's Argon2 path for newly created/refreshed password hashes.
• Safe rollout plan:
  1. enable Argon2 first in staging
  2. validate login/reset latency and memory usage
  3. deploy with auth.argon2Enabled: true
  4. allow successful password logins/resets to migrate active users forward over time

Abuse Protection

• MoFaCTS enforces layered auth throttles:
  • Meteor DDP connection-level limits
  • server-side IP + identifier throttles for signup, password reset, verification resend, and password login
  • soft lockouts for repeated password-login failures

MFA-Ready State

• The app remains password-only today.
• User records now carry authState metadata and sessions carry loginParams.authSessionState.
• These fields are intentionally shaped to support later MFA/step-up flows without changing current user behavior.

Common Mistakes

• Mismatch between ROOT_URL in the active private env file and its mounted settings file.
• Invalid SMTP URL encoding (special characters in password not URL-encoded).
• Changing encryptionKey after data has already been encrypted.
• Putting secrets under public (client-visible).

See Also

• Deployment Guide
• Local Install
• Remote Install
• Developer Reference Guide
• Troubleshooting