meteor-deployment

Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

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+	24

Mismatch causes runtime errors. Run meteor node -v to confirm.

Decision flow

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.

Docker / Kubernetes? meteor build --directory ./build --server-only

skips platform-specific mobile artifacts. Use --architecture os.linux.x86_64 for a cross-build.

SSH to a Node host? Same meteor build, scp the bundle, install prod

deps under bundle/programs/server, run node main.js.

Vercel / Netlify / serverless? Not supported. Meteor needs a

long-lived Node process with a WebSocket.

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`

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:

bash

# 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>`.

For a Free app, pass a simple app name, not a custom domain:

bash

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.

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

x8664 Linux must pass `--architecture os.linux.x8664`.

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/.