meteor-deployment

Meteor deployment

meteor build produces a self-contained Node bundle that runs anywhere the matching Node.js version runs. Galaxy is the first-party host; Docker / Kubernetes / SSH-to-a-Node-host all work too.

For Android/iOS artifacts and native HCP compatibility, use meteor-native. Check actual native configuration as well as compatibility hashes: permission or other native configuration changes can require a new binary with an unchanged hash.

Match the Node version to the bundled Meteor Node:

Meteor	Node major
3.0	20
3.1 through 3.4	22
3.5.x and 3.6-beta.0	24
3.6-beta.1 through beta.3	26 (26.8.2)
3.6-rc.0	26 (26.10.0)

Run meteor node -v and meteor npm -v in the target app to confirm. Meteor 3.6-beta.1 through beta.3 bundle npm 11.19.0. Match the deployed runtime and native dependency build environment to that release; rebuild and test native npm modules for Node 26 and the production architecture before deploying these betas. Meteor 3.6-rc.0 bundles npm 11.19.1. An extracted bundle records its exact Node version in bundle/.node_version.txt; use that metadata when the source tool is unavailable. The host installer prerequisite does not select the bundled runtime.

Decision flow

1. Galaxy? Choose Git Push to Deploy or the Meteor CLI. Configure Galaxy's settings source, build hooks, health checks, and domains from references/galaxy.md.
2. Docker / Kubernetes? meteor build --directory ./build --server-only skips platform-specific mobile artifacts. Use --architecture os.linux.x86_64 for a cross-build.
3. SSH to a Node host? Same meteor build, scp the bundle, install prod deps under bundle/programs/server, run node main.js.
4. Vercel / Netlify / serverless? Not supported. Meteor needs a long-lived Node process with a WebSocket.

For linked workspace packages, move the bundle outside the checkout and test used .bin commands and adjacent resource reads without source access. 3.6-beta.3 fixes copied command links; verify older tools before relying on them. Preserve the manager/lockfile and do not patch generated links. See database boundaries for beta.3's local MongoDB 8 versus an external database.

Required environment

Var	Purpose
ROOT_URL	Absolute external URL (e.g. https://app.example.com).
MONGO_URL	mongodb://... connection string.
MONGO_OPLOG_URL	Optional Mongo replica oplog URL.
PORT	Listen port. Default 3000.
BIND_IP	Network interface. Default 0.0.0.0.
METEOR_SETTINGS	JSON; populates Meteor.settings.
MAIL_URL	SMTP for Email.send and account emails.

ROOT_URL is the external URL the browser sees, not the cluster-internal service URL. OAuth redirects, Meteor.absoluteUrl, and CSP all rely on it.

On Meteor 3.0 through 3.4, configure MONGO_OPLOG_URL for oplog-backed reactivity; without it, Meteor polls. Meteor 3.5+ can use core change streams without that variable and falls back to oplog or polling when needed. Atlas hosting alone does not add core change-stream support to an older Meteor app.

settings.json

{
  "public": { "appName": "My App", "stripePublishableKey": "pk_live_..." },
  "stripeSecretKey": "sk_live_...",
  "oauthSecretKey": "16-byte-base64==",
  "mailgun": { "apiKey": "..." }
}

Top-level keys: server only. public subtree: shipped to the client.

Load:

# dev
meteor run --settings settings.json

# production
METEOR_SETTINGS=$(cat settings.json) node bundle/main.js

Galaxy

Choose one deployment path:

Path	Use when	Trigger
Push to Deploy	Galaxy should build a connected GitHub or Bitbucket branch.	Every push to the selected branch.
Meteor CLI	A person or CI pipeline controls each upload.	meteor deploy <app-name>.

Check meteor whoami; add --owner my-account to select a specific user or organization. For a new Free app, pass a simple app name, not a custom domain:

meteor login
meteor deploy myapp --free --settings settings.json

DEPLOY_HOSTNAME=eu-west-1.galaxy-deploy.meteor.com \
  meteor deploy myapp --plan essentials --settings settings.json

Galaxy assigns a myapp.sandbox.galaxycloud.app hostname on Free or a regional myapp.<region>.galaxycloud.app hostname on paid plans. Add custom domains in the dashboard. The active primary domain controls ROOT_URL.

For an existing app, confirm its current hostname, region, and owner before redeploying. --plan and --container-size select creation settings; change an existing app's plan or size in the dashboard. Optionally add --mongo to provision free shared MongoDB for testing, following the Mongo TLS guidance. It has no backups and is not recommended for production.

Galaxy injects PORT, ROOT_URL, and METEOR_SETTINGS. Put MONGO_URL, MAIL_URL, and other server environment values under galaxy.meteor.com.env in the Galaxy settings JSON. Do not assume a CLI --settings file overrides Repository Mode.

See references/galaxy.md for settings modes, Push to Deploy builds, zero-downtime rollout and rollback, proxies, Mongo TLS, memory, and custom base images.

Docker

See references/docker.md for a working multi-stage Dockerfile. Build the bundle in one stage, install server deps and run in a smaller one. --server-only skips platform-specific mobile application builds, but it does not omit the browser client or create an API-only bundle. Meteor still builds the web.cordova client target used for hot code push.

Hot code push

autoupdate provides production hot code push. It detects a new client version over DDP, applies stylesheet-only changes without reloading when possible, and otherwise performs a full browser reload. Remove autoupdate from .meteor/packages to disable HCP.

hot-module-replacement is different. It replaces accepted JavaScript modules during development and falls back to HCP when a module cannot accept the update. HMR is disabled in production and on unsupported web architectures. There is no Meteor.disableClientResourceFetch switch in the current public API.

Anti-patterns

• Commit settings.json with production secrets. Use a CI secret store or env vars; load with METEOR_SETTINGS=$(cat ...) at startup.
• Set ROOT_URL to the internal Kubernetes service URL. Use the external HTTPS URL or OAuth redirects and Meteor.absoluteUrl break.
• Run a Node version that does not match the bundled Meteor Node. Always check meteor node -v.
• Build on the wrong architecture. M-series Mac developers building for x86_64 Linux must pass --architecture os.linux.x86_64.
• Commit Galaxy settings with credentials or expect Repository Mode to read a CLI --settings file. Keep secrets in Galaxy Mode or a secret store.
• Hardcode Galaxy's port, load-balancer IP, or regional DNS target. Read $PORT and copy current network values from the app dashboard.
• Bundle the source tree into the Docker image alongside the built bundle. Use multi-stage; the runtime image holds only bundle/.

See also

• references/settings-and-env.md
• references/galaxy.md
• references/docker.md
• references/eval-cases.md