Create a gist now

Instantly share code, notes, and snippets.

What would you like to do?
Simple guide to running TileMill remotely on an AWS instance

Remote TileMill

This guide describes a simple and fast way to launch TileMill in the cloud. Reasons you might want to do this (vs running locally) include:

  • You need more processing power
  • You want to work realtime styling maps with other cartographers in different places
  • You are keen to learn more about the command line, ssh, and TileMill core usage

Get setup with Amazon AWS

Go to and hit "sign up" to create an Amazon account if you don't already have one.

Login to the AWS console

Go to and navigate to the ec2 section ( This is where you will be managing your instance(s) once launched.

Launch an instance

Since we need an Ubuntu AMI for TileMill to run on a great way to find and launch one is to use the interface. Go to and choose your preferred EC2 region from the drop-down on the right. Then choose a 64 bit "EBS boot" of the most recent Ubuntu version (at the time of writing this was Quantal). "EBS boot" means that you will be able to start and stop this instance at any time without loosing machine state vs "instance store" which means that if you stop the instance all your data is gone.

Hit the little orange arrow to the right for your desired AMI and it will send you back to the AWS console with a "Request Instance Wizard" pop up to help you launch this specific AMI.

Request Instance Wizard

The wizard has 5 steps, and here is a rundown:

Choose and AMI

Simply click continue, should be all good

Instance Details

Choose and instance type with at least >= 2GB ram and multiple cores. Go as big as you like, just make sure you don't let the machine run for more than a few days or forget to shut it down otherwise you'll be surprised by the bill at the end of the month. See this page for pricing details per instance type.

Then hit continue and you'll be sent to the "Advanced Instance Options" sub-page. No changes needed here, but be aware of what the "shutdown behavior is". If it is terminate then it means you will loose your data when you stop the instance (no matter whether it is EBS or instance store). If it is stop then it means your data will be saved as an EBS volume until you terminate it. EBS volumes do cost a $ per month, but not much.

Then hit continue and pass through the "Storage Device Configuration" without changes.

Create Key Pair

Now, at this step you need to choose a keypair name that you'll use to login via ssh with later on. If you don't have any keys create them now. Keep in mind here that keypairs are specific to ec2 region.

Configure Firewall

This step is critical in that to be able to access this machine remotely you will need to open up the right ports to be able to ssh into the instance and view TileMill on its default custom port.

Create a new security group with at least three open ports. Use as the source and add rules for ports 22, 20009, and 20008 for ssh, the TileMill UI, and the TileMill tileserver, respectively.

This is the last step, now hit continue and "Launch". After launching you should see your instance booting on the instances page.

Connecting to the instance

Once the instances page shows a big green ball indicating the instance is running, click on it to display its metadata. Scroll down through the description details to find the "Public DNS" url and copy it.

Now open up a terminal on your local machine and type:

ssh -i <yourkey>.pem ubuntu@<instance-dns>

An example here would be:

export EC2_KEY="mykey.pem"
ssh -i ${EC2_KEY} ubuntu@${TILEMILL_HOST}

Just exchange <yourkey> for the full path to the keypair that you downloaded and <instance-dns> with the full url that you just copied.

Installing TileMill

Once on the machine you can install the latest version of TileMill by doing:

echo 'yes' | sudo apt-add-repository ppa:developmentseed/mapbox
sudo apt-get -y update
sudo apt-get -y upgrade
sudo apt-get -y install libmapnik nodejs tilemill

Running TileMill

To run TileMill you need to launch it from the command line by disabling the built-in UI (since your server does not have a GUI system installed).

See for all the details on this, but basically you want to do:

cd /usr/share/tilemill
./index.js --server=true --listenHost= --coreUrl=${TILEMILL_HOST}:20009 --tileUrl=${TILEMILL_HOST}:20008

Setting up project files

Since TileMill does not offer any way to upload project files you will need to get data onto the machine via ssh.

Once you have started TileMill once on the remote server the documents folder should exist at /home/ubuntu/Documents/MapBox. Say you have self contained project on your local machine you'd like to upload you could do this by opening a terminal locally and typing this command:

export PROJECT_NAME="<somemap>"
scp -i ${EC2_KEY} -r ~/Documents/MapBox/project/${PROJECT_NAME} ubuntu@${TILEMILL_HOST}:/home/ubuntu/Documents/MapBox/

Make sure to change <somemap> to refer to the name of the project folder that exists locally which you want to upload.

Using git may be easier to transfer files and keep them versioned. Say you wanted to populate your remote server with the example projects from You could do that like:

sudo apt-get -y install git
cd /home/ubuntu/Documents/MapBox/project
git init .
git remote add origin git://
git pull origin master

Accessing TileMill

After starting tilemill on the remote server, then paste $TILEMILL_HOST:20009 into a web browser and you should see your projects.

Learn more

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment