Meteor Up Documentation

Meteor Up is a CLI tool for deploying Meteor applications to your own servers using Docker. Key capabilities include:

• Deployment: Single command server setup and deployment to multiple servers with optional load balancing and sticky sessions.
• Configuration: Management of Environment Variables and support for Meteor settings.json.
• Security & Auth: Password or Private Key (pem) based server authentication, and running apps within Docker for isolation.
• Reliability: Auto-restart on app crashes, auto-start after server reboots, and automatic reversion to the previous version if a deployment fails.
• Networking: Support for Let's Encrypt and custom SSL certificates.
• Observability: Access logs directly from the terminal with log tailing support.

Meteor Up supports Meteor 1.2 and newer.

Important: To use Meteor 1.4 or newer, you must change the Docker image used for deployment. A list of compatible Docker images is available in the official documentation.

Meteor Up manages your application using Docker and MeteorD.

Key behaviors:

• App Location: The running Meteor bundle is located at /opt/<appName>/current on the server.
• Container Lifecycle: The application runs in a demonized Docker container with the --restart=always flag.
• Logs: Managed via Docker.
• MongoDB: If used, MongoDB runs in its own Docker container, bound to the local interface on port 27017 (not accessible from outside the server). The database name defaults to <appName>.

Hooks allow a plugin to run logic before or after commands executed by other plugins. Hook names follow the pattern pre.<command> or post.<command>.

Important: Never call a command handler function directly. Always use api.runCommand(commandName) to ensure that the command's associated hooks are triggered correctly. Command names are formatted as pluginName.commandName (e.g., mongo.restart).

module.exports = {
  hooks: {
    'post.deploy'(api) {
      const config = api.getConfig();
      if (config.app && config.app.type === 'elixir') {
        api.runCommand('elixir.deploy');
      }
    },
    'pre.mongo.start'(api) {
      api.runCommand('elixir.adjustMongoConfig');
    }
  }
};

Use mup deploy to bundle your Meteor project locally and deploy it to the configured remote servers.

If a previous deployment failed due to network issues or configuration errors, you can use the --cached-build flag to reuse the last successful build instead of rebuilding from scratch.

mup deploy

# To use the previous build:
mup deploy --cached-build

The mup deploy command performs the following lifecycle:

1. Builds your app using meteor build.
2. Uploads the app bundle, start script, and environment variables to your servers.
3. Runs the start script on the server.
4. Verifies that the app successfully started.

Troubleshooting Uploads: If a deployment fails due to a network error during the bundle upload, use the --cached-build flag. This skips the build step and uses the bundle from your last successful build.

mup deploy

# If upload fails due to network errors:
mup deploy --cached-build

Meteor Up is not backward compatible with Meteor Up 0.x or mupx. The runtime has changed to Docker, and the configuration format is different.

Migration Steps (assuming appName is meteor):

1. Clean up old containers:

   docker rm -f meteor
   docker rm -f mongodb
   docker rm -f meteor-frontend

2. Initialize new configuration: Run mup init to create a new configuration file.

3. Setup and Deploy: Run mup setup followed by mup deploy.

# Clean up old containers
docker rm -f meteor
docker rm -f mongodb
docker rm -f meteor-frontend

# Initialize and deploy
mup init
mup setup
mup deploy

Run the setup command to install all necessary dependencies on your target server and prepare it for deployment.

Important for Windows users: Use mup.cmd instead of mup when running commands in Command Prompt.

If you change your configuration, run mup setup again. It is safe to run multiple times.

You can use the --verbose flag to see the specific tasks being performed.

In version 1.4 and later, several configuration keys were deprecated in favor of a more secure and feature-rich reverse proxy implementation.

Deprecated keys:

• meteor.ssl
• meteor.nginx
• meteor.docker.imageFrontendServer

Action: Instead of using these keys, you should use the reverse proxy implementation. The reverse proxy handles custom certificates and Let's Encrypt more securely and provides additional features. Refer to the reverse proxy documentation for implementation details.

To start using Meteor Up in an existing Meteor application, create a .deploy directory at your project root and run the initialization command. It is standard practice to keep your settings.json and mup configuration within this folder.

cd path/to/app
mkdir .deploy && cd .deploy
mup init

Meteor Up uses a shared NGINX reverse proxy to handle SSL and routing for multiple apps on a server. This replaces the deprecated app.ssl and app.nginx settings.

To set up the proxy, add a proxy section to your configuration. If you are using Swarm, you must specify the servers in proxy.servers.

Important: When setting up the proxy for the first time, you must stop all running apps on the servers, then run mup setup and mup reconfig.

mup stop
mup setup
mup reconfig

module.exports = {
  // ... rest of config

  proxy: {
    // (Required when using swarm) Servers to run the reverse proxy on.
    servers: {
      one: {}
    },
    // comma-separated list of domains your website
    // will be accessed at.
    domains: 'website.com,www.website.com'
  }
};

Plugins are npm packages that extend Meteor Up functionality. You can install them locally to your app/config folders or globally using npm.

To activate a plugin, add its name (or relative path) to the plugins array in your Meteor Up configuration file.

module.exports = {
  // ... rest of config

  plugins: ['name-of-plugin', 'name-of-other-plugin', '../path/to/plugin']
};