Custom Deployment

If you want to figure out your hosting solution completely from scratch, the Meteor tool has a command meteor build that creates a deployment bundle containing a plain Node.js application. This approach gives you complete control over your deployment infrastructure but requires more manual setup and maintenance compared to managed solutions.

Building Your Application

The meteor build command creates a deployment bundle that can run on any server with Node.js and MongoDB.

Prerequisites

Before building, ensure all npm dependencies are installed:

npm install --production

Any npm dependencies must be installed before issuing the meteor build command to be included in the bundle.

Build Command

Create a production bundle for deployment:

meteor build /path/to/build --architecture os.linux.x86_64

It’s important that you build your bundle for the correct architecture. For example, if deploying to a Ubuntu Linux server, use os.linux.x86_64.

Build Options

--architecture - Specify the target architecture (e.g., os.linux.x86_64)
--directory - Build to a directory instead of a tarball
--server-only - Don’t build mobile apps
--server - Set the ROOT_URL (for mobile builds)

Examples:

# Build as directory (no tarball)
meteor build --directory /build --server-only

# Build with specific server URL
meteor build /path/to/build --server https://my-app.com

Understanding the Bundle

The meteor build command produces a .tar.gz file containing:

bundle/ - The application bundle directory
- main.js - Application entry point
- programs/ - Server and client code
  - server/ - Server-side code and npm dependencies
  - web.browser/ - Client-side code
- .node_version.txt - Required Node.js version
- star.json - Bundle metadata

Deployment Steps

Build the Application

Create the deployment bundle:

npm install --production
meteor build /path/to/build --architecture os.linux.x86_64

Transfer to Server

Copy the .tar.gz file to your server:

scp /path/to/build/*.tar.gz user@server:/path/to/deploy/

Extract the Bundle

On the server, extract the bundle:

cd /path/to/deploy
tar -xzf *.tar.gz

Install Server Dependencies

Install Node.js dependencies for the server bundle:

cd bundle/programs/server
npm install --production

Run the Application

Start the application with required environment variables:

cd /path/to/deploy/bundle
MONGO_URL=mongodb://localhost:27017/myapp \
ROOT_URL=http://my-app.com \
PORT=3000 \
node main.js

Required Environment Variables

Your Meteor application requires these environment variables to run:

ROOT_URL

The base URL for your Meteor project:

ROOT_URL=https://my-app.com

This is used to generate URLs to your application by various packages, including the accounts package.

MONGO_URL

A MongoDB connection string URI:

MONGO_URL=mongodb://user:password@host:port/database

In production, you must specify a MONGO_URL. In development, Meteor automatically connects to a local MongoDB instance.

PORT

The port at which the application is running:

PORT=3000

METEOR_SETTINGS (Optional)

Settings as a stringified JSON object:

METEOR_SETTINGS='{"public":{"analyticsKey":"xyz"}}'

Node.js Version

The environment you choose will need the correct version of Node.js and connectivity to a MongoDB server. To find out which version of Node you should use:

Run meteor node -v in the development environment
Check the .node_version.txt file within the bundle
For Meteor 3.x, you’ll need Node.js 20.x

If you use a mismatched version of Node when deploying your application, you will encounter errors!

Example Deployment Script

Here’s a complete deployment script you can adapt:

deploy.sh

#!/bin/bash

# Configuration
APP_NAME="my-meteor-app"
DEPLOY_DIR="/var/www/$APP_NAME"
BUILD_DIR="/tmp/meteor-build"
MONGO_URL="mongodb://localhost:27017/$APP_NAME"
ROOT_URL="https://my-app.com"
PORT=3000

# Build the application
echo "Building application..."
meteor npm install --production
meteor build $BUILD_DIR --architecture os.linux.x86_64

# Stop the running application
echo "Stopping application..."
pm2 stop $APP_NAME || true

# Extract the bundle
echo "Extracting bundle..."
cd $DEPLOY_DIR
tar -xzf $BUILD_DIR/*.tar.gz

# Install dependencies
echo "Installing dependencies..."
cd bundle/programs/server
npm install --production

# Start the application
echo "Starting application..."
cd $DEPLOY_DIR/bundle
PORT=$PORT \
ROOT_URL=$ROOT_URL \
MONGO_URL=$MONGO_URL \
pm2 start main.js --name $APP_NAME

echo "Deployment complete!"

Process Management

For production deployments, use a process manager to keep your application running:

PM2

PM2 is a popular Node.js process manager:

# Install PM2
npm install -g pm2

# Start your app with PM2
cd /path/to/deploy/bundle
pm2 start main.js \
  --name my-meteor-app \
  -i max \
  --env production

# Set environment variables
pm2 set my-meteor-app:ROOT_URL https://my-app.com
pm2 set my-meteor-app:MONGO_URL mongodb://localhost:27017/myapp
pm2 set my-meteor-app:PORT 3000

# Save PM2 configuration
pm2 save

# Setup PM2 to start on system boot
pm2 startup

Systemd Service

Alternatively, create a systemd service:

/etc/systemd/system/meteor-app.service

[Unit]
Description=Meteor Application
After=network.target

[Service]
Type=simple
User=meteor
WorkingDirectory=/var/www/my-meteor-app/bundle
Environment="ROOT_URL=https://my-app.com"
Environment="MONGO_URL=mongodb://localhost:27017/myapp"
Environment="PORT=3000"
ExecStart=/usr/bin/node main.js
Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable meteor-app
sudo systemctl start meteor-app
sudo systemctl status meteor-app

Reverse Proxy Setup

For production deployments, use a reverse proxy like Nginx to:

Handle SSL/TLS termination
Serve static files efficiently
Load balance across multiple instances
Add security headers

Nginx Configuration

/etc/nginx/sites-available/meteor-app

upstream meteor_app {
  server 127.0.0.1:3000;
}

server {
  listen 80;
  server_name my-app.com;
  return 301 https://$server_name$request_uri;
}

server {
  listen 443 ssl http2;
  server_name my-app.com;

  ssl_certificate /etc/letsencrypt/live/my-app.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/my-app.com/privkey.pem;

  location / {
    proxy_pass http://meteor_app;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    
    # WebSocket support
    proxy_read_timeout 86400;
  }
}

Meteor Up Alternative

Meteor Up (mup) is a third-party, open-source tool that automates the manual steps of using meteor build and deploying to your server. Meteor Up can SSH into any server running Ubuntu or Debian and handle the deployment process for you. Get started with the Meteor Up tutorial.

Key Features

Automated deployment via SSH
Docker-based deployments
Zero-downtime deployments
SSL certificate management
MongoDB setup and management
Environment variable management
Deployment rollback support

AWS Elastic Beanstalk Plugin

The mup-aws-beanstalk plugin deploys Meteor apps to AWS Elastic Beanstalk instead of a server. It supports:

Autoscaling
Load balancing
Zero downtime deploys
Managed infrastructure

Best Practices

Use Process Managers

Always use a process manager like PM2 or systemd to ensure your application restarts automatically on crashes or server reboots.

Implement Reverse Proxy

Use Nginx or similar reverse proxy for SSL termination, static file serving, and additional security.

Build for Correct Architecture

Always specify the correct architecture when building to avoid runtime errors.

Version Control Deployments

Keep track of deployed versions and maintain deployment scripts in version control.

Monitor Application Health

Implement health checks and monitoring to detect issues early.

Backup MongoDB Regularly

Set up automated MongoDB backups to prevent data loss.

Troubleshooting

Build Errors

Ensure all npm dependencies are installed before building
Check that you have enough disk space for the build
Verify you’re using a supported Node.js version

Runtime Errors

Check that all environment variables are set correctly
Verify MongoDB is accessible and credentials are correct
Ensure the Node.js version matches the one used to build
Check application logs for specific error messages

Connection Issues

Verify firewall rules allow traffic on the specified port
Check that reverse proxy is properly configured
Ensure WebSocket connections are supported
Verify ROOT_URL matches the actual domain

Performance Issues

Use a production MongoDB with proper indexing
Implement caching strategies
Configure CDN for static assets
Use WebAppInternals.setBundledJsCssPrefix() for CDN
Monitor resource usage (CPU, memory, disk)

Build System

Deployment

Performance

Contributing

Custom Deployment

Building Your Application

Prerequisites

Build Command

Build Options

Understanding the Bundle

Deployment Steps

Required Environment Variables

ROOT_URL

MONGO_URL

PORT

METEOR_SETTINGS (Optional)

Node.js Version

Example Deployment Script

Process Management

PM2

Systemd Service

Reverse Proxy Setup

Nginx Configuration

Meteor Up Alternative

Key Features

AWS Elastic Beanstalk Plugin

Best Practices

Troubleshooting

Build Errors

Runtime Errors

Connection Issues

Performance Issues

Additional Resources

Build System

Deployment

Performance

Contributing

Documentation Index

​Building Your Application

​Prerequisites

​Build Command

​Build Options

​Understanding the Bundle

​Deployment Steps

​Required Environment Variables

​ROOT_URL

​MONGO_URL

​PORT

​METEOR_SETTINGS (Optional)

​Node.js Version

​Example Deployment Script

​Process Management

​PM2

​Systemd Service

​Reverse Proxy Setup

​Nginx Configuration

​Meteor Up Alternative

​Key Features

​AWS Elastic Beanstalk Plugin

​Best Practices

​Troubleshooting

​Build Errors

​Runtime Errors

​Connection Issues

​Performance Issues

​Additional Resources

Building Your Application

Prerequisites

Build Command

Build Options

Understanding the Bundle

Deployment Steps

Required Environment Variables

ROOT_URL

MONGO_URL

PORT

METEOR_SETTINGS (Optional)

Node.js Version

Example Deployment Script

Process Management

PM2

Systemd Service

Reverse Proxy Setup

Nginx Configuration

Meteor Up Alternative

Key Features

AWS Elastic Beanstalk Plugin

Best Practices

Troubleshooting

Build Errors

Runtime Errors

Connection Issues

Performance Issues

Additional Resources