Articles on: Meteor Apps

Deploy a new Meteor app using the CLI

Deploying your Meteor app to Galaxy using the command line is a powerful and flexible way to manage your app’s deployment, scaling, and monitoring directly from your terminal. Whether you’re launching a new app or integrating deployment into a CI/CD pipeline, this guide provides clear, step-by-step instructions to help you succeed. Before you begin, ensure you’re logged into your Meteor Developer Account with the necessary permissions for Galaxy. You can verify this with the meteor whoami command.

This guide covers all aspects of deploying your Meteor app to Galaxy, including choosing a hostname, selecting a region, and using advanced deployment options. Let’s get started!

Command: `meteor whoami`

To deploy your app, you need to be logged into your Meteor Developer Account with appropriate Galaxy permissions. The meteor whoami command verifies your login status.

Command:

    meteor whoami

What it does: Displays your username if logged in or prompts you to log in if not.
Why it’s important: Ensures you have the correct permissions to deploy, preventing errors.
Pro tip: If you’re not logged in, run meteor login to authenticate. For automated deployments, consider using a deployment token (covered later).

Command: `meteor deploy`

The meteor deploy command is the core tool for deploying your Meteor app to Galaxy. It allows you to deploy your app to a specified hostname and customize the deployment with various flags.

Basic syntax:

    meteor deploy [hostname]

Example:

    meteor deploy yourapp.meteorapp.com

What it does: Deploys your app to the US East region on the Essential plan with a Tiny container.

Key considerations:

Replace [hostname] with your desired domain (e.g., yourapp.meteorapp.com or a custom domain like www.yourappname.com).
By default, the app deploys to US East. Use the DEPLOY_HOSTNAME environment variable to specify other regions.

Pro tip: Instead of the full hostname, you can use just your app name. Example: meteor deploy yourapp

Available Flags

The meteor deploy command supports several flags to customize your deployment. Below is a comprehensive list of all available flags:

Flag	What it does
`--delete, -D`	Permanently delete this deployment, including all stored data.
`--debug`	Deploy in debug mode (do not minify the code).
`--settings, -s [file]`	Set optional data for Meteor.settings from a JSON file.
`--allow-incompatible-update`	Allow packages to be updated to potentially incompatible versions if needed.
`--deploy-polling-timeout [ms]`	Set the timeout for waiting for build/deploy success/failure (default 15 minutes).
`--no-wait`	Exit after uploading the code, without waiting for the deploy to conclude.
`--cache-build`	Reuse the build if the git commit hash is the same (requires Meteor 1.11+ and app in Git repository).
`--free`	Deploy on Galaxy's free plan with Shared MongoDB (must be used with `--mongo`).
`--plan [plan]`	Set the app plan to professional, essentials, or free. This overwrites the `--free` flag.
`--mongo`	Use Galaxy’s Shared MongoDB service. If no `MONGO_URL` is provided in settings, Galaxy will create a database for your app.
`--container-size [size]`	Set the container size to tiny, compact, standard, double, quad, octa, or dozen.
`--build-only`	Build the app without deploying it (available for Meteor 2.3+).
`--owner [owner]`	Deploy the app under a specific username or organization (requires deploy privileges).

Detailed Explanations of Key Flags

Let’s explore some of these flags in more detail to understand their use cases and best practices.

Plan and Cost

--free: Use this flag with --mongo to deploy your app on Galaxy’s free plan, which includes Shared MongoDB. Ideal for testing or small projects. Note that resource limits apply; see the Pricing Page for details.
--plan: Specify a plan (professional, essentials, or free). This flag overwrites --free, so if you use both, --plan takes precedence.

Database

--mongo: Required when using the free plan. If no MONGO_URL is provided in your settings file, Galaxy will automatically create a database for your app in its shared cluster and update your settings with the database URL.

Settings

--settings : Allows you to pass a JSON file containing environment-specific settings (e.g., API keys, database URLs). These settings are available at runtime via Meteor.settings on the server. If the JSON contains a public key, Meteor.settings.public is also available on the client. Example:

    meteor deploy myapp.meteorapp.com --settings settings.json

Pro tip: Settings persist across deployments until you specify a new settings file. To unset Meteor.settings, deploy with an empty settings file.

Build Options

--cache-build: Caches the build process if the git commit hash is unchanged, speeding up subsequent deployments. Requires Meteor 1.11+ and your app must be in a Git repository.
--build-only: Builds your app without deploying it, useful for testing or CI/CD pipelines. Available for Meteor 2.3+.
--debug: Deploys your app without minifying the code, aiding in debugging.

Deployment Control

--no-wait: Exits immediately after uploading your app’s code, without waiting for the deployment to complete.
--deploy-polling-timeout: Sets how long Meteor waits for build/deploy success or failure after uploading code (default: 15 minutes).

Package Management

--allow-incompatible-update: Allows Meteor to update packages to potentially incompatible versions if needed to satisfy all package constraints. Use cautiously.

Deletion

--delete, -D: Permanently removes your app from Galaxy, including all data. Use with extreme caution.

Ownership

--owner: Deploys your app under a specific username or organization. Useful in team environments or when deploying on behalf of others.

Container Size

--container-size: Sets your app’s container size (tiny, compact, standard, double, quad, octa, dozen). Larger sizes provide more resources but may increase costs on paid plans.

Available Regions (DEPLOY_HOSTNAME)

Galaxy supports deployment in multiple regions to optimize performance and compliance. You can specify the region by setting the DEPLOY_HOSTNAME environment variable before running the meteor deploy command.

Available regions:

Region	DEPLOY_HOSTNAME	Hostname Format
US East	`galaxy.meteor.com`	`hostname.meteorapp.com`
EU West	`eu-west-1.galaxy.meteor.com`	`hostname.eu.galaxy.meteor.com`
Asia-Pacific	`ap-southeast-2.galaxy.meteor.com`	`hostname.au.galaxy.meteor.com`

Example (Deploying to EU West):

    DEPLOY_HOSTNAME=eu-west-1.galaxy.meteor.com meteor deploy yourapp.eu.meteorapp.com

For Windows users:

Set the environment variable first:

SET DEPLOY_HOSTNAME=eu-west-1.galaxy.meteor.com
meteor deploy yourapp.eu.meteorapp.com

Why it’s important: Choosing a region closer to your audience reduces latency.

Choosing a Hostname

You must specify a hostname for your app, either a meteorapp.com subdomain or a custom domain.

Using a meteorapp.com subdomain:

The format depends on the region (see table above).
Example: yourapp.meteorapp.com for US East.

Using a custom domain:

Example: www.yourappname.com.
Point your DNS to galaxy-ingress.meteor.com. See the DNS configuration guide for detailed instructions.

Deployment Token

For automated deployments (e.g., CI/CD pipelines), use a deployment token, which is valid for 90 days.

Steps:

Log in and out of your account using Meteor's authentication system.
You can pass METEOR_SESSION_FILE=token.json before meteor login to generate a login session token so you don't have to share your login credentials with third-party service providers. Example:

        METEOR_SESSION_FILE=token.json meteor login

Deploy as usual with meteor deploy.

Why it’s useful: Enables automation without interactive login.

Cost Considerations

Deploying with the command line incurs no additional cost beyond your chosen plan. The meteor deploy command uses your local machine for building and deploying. The free plan (--free with --mongo) is cost-free but has resource limitations. For paid plans, refer to the pricing page.

Troubleshooting Tips

Deployment fails: Verify your login with meteor whoami and ensure your account has Galaxy permissions.
Hostname issues: Check that your hostname is unique and correctly formatted for the region.
Build errors: For -cache-build, ensure your app is in a Git repository. For -build-only, verify your build configuration.

Updated on: 18/06/2025