@empirica/meteor-deploy

A simple tool to facilitate deploying meteor projects to the cloud for production.

What is @empirica/meteor-deploy?

@empirica/meteor-deploy is yet another production deployment tool for meteor projects.

It has been specifically tailored to deploy empirica.ly experiments, however it can also be used for other projects.

@empirica/meteor-deploy uses docker containers and pulumi templates facilitate deployments to your own cloud account (currently only AWS is supported).

Why do we need @empirica/meteor-deploy?

There are plenty of alternative ways to deploy meteor projects for production:

• Meteor Galaxy - Meteor's commercial hosting offering
• Meteor Up - A powerful open-source tool that deploys a meteor projects into docker containers.

For Meteor projects such as Empirica, Meteor's Galaxy hosting does not offer compute instances with sufficient CPU and Memory to allow for optimal performance. For most meteor projects that is not problem as Galaxy is excellent at facilitating horizontal scalability, however Empirica projects do not support that.

@empirica/meteor-deploy, just like Meteor Up allows you to deploy your own MongoDB instance, so that you don't have to run use a professional MongoDB hosting service.

@empirica/meteor-deploy creates all the infrastructure resources that you need on the cloud, so you don't have to spend time configuring infrastructure and deploying updates to it. When using Meteor Up you would still need to go through some cumbersome steps to deploy your docker-containers to the cloud.

However if you do need production grade database-hosting (with full back-up solutions and scalability) and if you need your application deployment to scale horizontally, @empirica/meteor-deploy may not be the right tool for you.

How to use @empirica/meteor-deploy?

Pre-requisites

Before we begin you need to do the following:

1. Meteor - If you haven't done this already, you will need to install meteor.
2. Node JS - meteor-deploy requires a separate node-js installation, because meteor's inbuilt nodejs version is out of date. How to install nodejs
3. Docker - meteor-deploy instructs pulumi to build a docker image. For this you need to install docker.

You will also need an up-to-date version of meteor installed.

Deploy your project

Install @empirica/meteor-deploy through npm, by running the following command in your meteor projects' directory.

meteor npm install --save-dev @empirica/meteor-deploy -y

Enable your project for deployments with default configuration:

npx meteor-deploy init my-deployment-project

Execute the deployment to your cloud:

npx meteor-deploy pulumi up

Update deployment with new versions of your meteor project

After making changes to your meteor project, you can update your deployment simply through pulumi:

npx meteor-deploy pulumi up

Update with new versions of @empirica/meteor-deploy

Occasionally @empirica/meteor-deploy will issue new releases of the tool that might improve upon your infrastructure.

When a new release is available, run the following commands to update your deployment accordingly:

meteor npm update @empirica/meteor-deploy
npx meteor-deploy init
meteor npm install
npx meteor-deploy pulumi up

Advanced Configuration

Most configuration options can be directly configured (and automatically validated by through meteor-deploy).

See:

npx meteor-deploy stack configure aws-ecs-ec2 --help

Upgrade to a more powerful EC2 instance type

By default, meteor-deploy will use t2.micro instances. These are not very powerful. To upgrade the instance type run:

npx meteor-deploy stack configure aws-ecs-ec2 --instanceType t2.medium --app:memory: 1024 --db:memory: 1024
npx meteor-deploy pulumi up

Enable HTTPS

Enabling transport encryption through HTTPS is highly recommended. You first need to create a certificate on the AWS Certificate manager (ACM).

For this you have three possible options:

• Request a public certificate, if your domain is public.
• Request a private certificate, for private domains
• Import your own certificate, if you already have a certificate that you can use.

Once your certificate is ready on ACM, copy its ARN and add it to the configuration:

npx meteor-deploy pulumi config set --path https.certificateArn <paste your certificate arn>
npx meteor-deploy pulumi config set --path domain.name mydomain.example.com
npx meteor-deploy pulumi up

You will need to manually create CNAME Record for your domain mydomain.example.com your DNS.

Automatically create CNAME entries for your domain through AWS Route53

If your domain is hosted on AWS Route53, then meteor-deploy can add the CNAME entry for you. Simply copy and paste your Route53 ZoneID like this:

npx meteor-deploy pulumi config set --path domain.name mydomain
npx meteor-deploy pulumi config set --path domain.zoneId <paste your zone id here>
npx meteor-deploy pulumi up

Note that when setting domain.zoneId, domain.name needs to be the name of the subdomain of the domain that the zone id refers to.

If no zone-id is set then domain.name needs to be a fully qualified domain name.

SSH Access

You can access EC2 instances that host the service through SSH. To enable SSH access you need a setup a ssh key.

Given a public ssh key at ~/.ssh/id_rsa.pub, add it to your stack:

npx meteor-deploy pulumi config set publicKey "$(cat ~/.ssh/id_rsa.pub)"
npx meteor-deploy pulumi up

Find your deployed cluster at https://console.aws.amazon.com/ecs/home and then open "ECS Instances". Click on the EC2 instance link in the table of running instances and look for it's ip domain alias to ssh into.

ssh ec2-user@<ec2 instance>

Destroying your deployment

If you wish to tear down all resources that pulumi has created on your cloud account, you can run:

npx meteor-deploy pulumi destroy

If you are using persistent storage, pulumi will warn you that you may want to reconsider destroying that volume, because it will permanently destroy any non-backed up data that it contains.

This will be displayed in a message like this:

Diagnostics:
  aws:ebs:Volume (leaderboard-dev):
    error: Preview failed: refusing to delete protected resource 'urn:pulumi:dev::leaderboard::aws:ebs/volume:Volume::leaderboard-dev'

Create a snapshot of that volume here to not lose its data.

Now go ahead un-protecting the volume and then destroying your deployment.

This will destroy the volume along with all the data stored on it

npx meteor-deploy pulumi state unprotect <urn>
npx meteor-deploy pulumi destroy

Restoring data from a snapshot

If you have an EBS volume snapshot, and you want to restore its data to your deployment do:

npx meteor-deploy pulumi config set --path database.storage.snapshotId <snapshot id>
npx meteor-deploy pulumi up

When deployed remove the snapshot so that it does not overwrite any newer persisted data.

npx meteor-deploy pulumi config rm --path database.storage.snapshotId