Building from source

WARNING: These instructions have not been tested on TileMill v1.x and newer, and may not work.

This documentation covers TileMill installation from source. This document is intended for users wishing to run TileMill on platforms other than Ubuntu, Mac OS X, or Windows (like other linux distributions), or for developers wishing to get a TileMill development version (aka. TileMill “master”) running on Ubuntu or Mac OS X.

Careful with versions

Before continuing decide whether you want to install the latest TileMill development code or whether you would like to install the latest stable TileMill release. Depending on what you choose then a different Node.js and/or Mapnik version will likely be required. Because TileMill relies heavily on Node.js and Mapnik, and both are very fast moving projects, you should pay special attention to this.

The instructions below assume you are going to install TileMill “master” - the latest in-development TileMill code from github. If you wish to install a specific TileMill version, then please see the Changelog for details about which version of Node.js and Mapnik were used successfully at the time of release.

Source install from scratch on Linux

A source install from scratch on Linux is likely required for most distributions. The reason is that TileMill requires a very recent version of Mapnik, which itself requires a very recent version of the boost libraries.

Specific working examples for Ubuntu and Fedora

We provide working examples of the recommended source install approach for Ubuntu and Fedora. See this gist for Ubuntu and this gist for Fedora. For all other systems the general discussion below should prepare you for success.

General Strategy

You will need a modern compiler, like gcc/g++ >= 4.6, and the python language at >= 2.5 to build both Node.js and Mapnik.

At the time of writing TileMill works with Mapnik >= 2.2. However, the interface between TileMill and Mapnik is the set a javascript bindings to Mapnik called node-mapnik, and the latest release of these bindings should build against any Mapnik version >= 2.0.x.

Mapnik requires a number of dependencies like boost, icu, proj4 and various image libraries. You will need these libraries installed ahead of time. On debian systems, for example, you can use the apt package manager to install all but boost. We say “all but boost” because usually the packaged versions of Boost are too old as you will need >= Boost 1.47. So, the basics for installing boost on Linux for Mapnik are:

1) Install development headers for boost dependencies. One debian systems you can do this like:

sudo apt-get install -y build-essential python-dev libbz2-dev libicu-dev

2) Install Boost from source

wget http://mapnik.s3.amazonaws.com/deps/boost_1_54_0.tar.bz2
tar xjvf boost_1_54_0.tar.bz2
cd boost_1_54_0
./bootstrap.sh
./b2 stage toolset=gcc --with-thread --with-filesystem --with-python --with-regex -sHAVE_ICU=1 -sICU_PATH=/usr/ --with-program_options --with-system link=shared
sudo ./b2 install toolset=gcc --with-thread --with-filesystem --with-python --with-regex -sHAVE_ICU=1 -sICU_PATH=/usr/ --with-program_options --with-system link=shared -d0
sudo ldconfig && cd ../

Now install the remaining Mapnik dependencies like icu, proj4, libpng, libjpeg, libtiff, libxml2, libltdl, and freetype. For help finding the package names for these tools on various linux distributions see the Mapnik wiki pages and for ubuntu systems do:

sudo apt-get install -y libxml2-dev libfreetype6-dev \
  libjpeg-dev libpng-dev libproj-dev libtiff-dev \
  libcairo2 libcairo2-dev python-cairo python-cairo-dev \
  libgdal1-dev postgresql-9.1 postgresql-server-dev-9.1 \
  postgresql-contrib-9.1 postgresql-9.1-postgis libsqlite3-dev

Now download the latest Mapnik release and build it from scratch:

wget http://mapnik.s3.amazonaws.com/dist/v2.2.0/mapnik-v2.2.0.tar.bz2
tar xf mapnik-v2.2.0.tar.bz2
cd mapnik-v2.2.0
./configure && make && sudo make install

Run the Mapnik tests to ensure it is working properly:

make test && cd ../

Next, Node.js. If you are building TileMill master, then you can see which Node.js versions are supported by checking the engines value in the package.json file here.

At the time of writing Node.js v0.10.13 was the latest release, works well with TileMill master (while v0.8.x is required for TileMill 0.10.x and older). Build node like:

NODE_VERSION="0.10.13"
wget http://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}.tar.gz
tar xf node-v${NODE_VERSION}.tar.gz
cd node-v${NODE_VERSION}
./configure && make && sudo make install
cd ../

Now, the last thing before building TileMill itself is to install a few more dependencies needed by TileMill or its node modules. One specific need is for its Desktop windowing UI. On Debian systems this package is called libwebkit-dev and can be installed with:

sudo apt-get install libwebkit-dev

On other linux systems webkit may or may not be available. It is only used for the optional TileMill desktop UI (optional because if not built TileMill can still be accessed through a web browser at http://localhost:20009), and can be disabled by removing the line referencing topcube in package.json

Also we need to install git (to download tilemill) and the google protobuf library (which latest node-mapnik requires). On debian systems you can do this like:

sudo apt-get install -y git protobuf-compiler libprotobuf-lite7 libprotobuf-dev

Finally, we are ready to install TileMill master itself:

git clone https://github.com/tilemill-project/tilemill.git
cd tilemill
npm install

If you hit errors, see the “Troubleshooting the npm install step” below.

If you happen to be on a server-only Linux machine (or built TileMill without topcube support), then check out the Ubuntu Service page which has details about running TileMill from the command line.

Source install on Mac OS X

On Mac OS X, you will first need a development environment. This is provided by Apple’s Xcode: either Xcode 3 or Xcode 4 should work on OS X 10.6 and above.

Mapnik >= 2.2.x, Node.js 0.8.x or 0.10.x, and Protocol buffers are required

We recommend installing these with the Homebrew package manager, because Homebrew will also make it easier to install their dependencies.

After installing Homebrew, install Mapnik and Node.js like:

brew update
brew install mapnik node git protobuf pkgconfig

For more details on Mapnik with Homebrew see the Mapnik wiki.

Then you can download TileMill and install:

git clone https://github.com/tilemill-project/tilemill.git
cd tilemill
npm install

If you hit errors, see the “Troubleshooting the npm install step” below.

Source install on Ubuntu Linux

These instructions should work for Ubuntu >= 10.04.

TileMill master install

For running the TileMill development version see the instructions at this gist.

Tagged source install

This is useful if you want a very fast way to get your own TileMill version running on Ubuntu to provide a patch against TileMill.

This works as a byproduct of our packaging process for the official TileMill releases, because during packaging we copy both the Node.js and Mapnik packages to keep static versions. Just be aware that this approach is not recommended unless you are very careful to get the source files for the correct TileMill tag and you are very careful not to have other source installs or PPA’s added to /etc/apt/sources.list.d that might include conflicting Mapnik or Node versions.

First install TileMill dependencies:

sudo apt-get install build-essential libwebkit-dev

Then add the Mapbox PPA and install node.js and mapnik from this location:

sudo add-apt-repository ppa:developmentseed/mapbox
sudo apt-get update
sudo apt-get install libmapnik libmapnik-dev mapnik-utils nodejs nodejs-dev npm

You should note that ppa:developmentseed/mapbox, which can be viewed here, also has TileMill packaged inside, but we did not install it. If we did actually install tilemill from this ppa this approach would be exactly like installing TileMill the official way on Ubuntu. Instead, if we wish to install from source, we should now grab the correct TileMill tag. At the time of this writing the TileMill version included in the PPA was 0.9.1, so we can get the sources for that tag from github and can install it like:

TILEMILL_TAG="v0.10.1"
git clone https://github.com/tilemill-project/tilemill.git
cd tilemill
git checkout ${TILEMILL_TAG}
npm install

Troubleshooting the npm install step

Upon a successful build npm install should output a dependency tree as an ascii diagram. If there was an error npm tends to hang and hitting enter will return to a command prompt. To see the error run npm install again (since the error in the first run will be buried in interleaved build output). If the error has to do with node-mapnik and you are trying to install a TileMill tag then you likely have a Mapnik version that is too old. If you are trying to install TileMill master then you might have a Mapnik version that is too recent.

Once the build is complete you can start TileMill with the following command from the tilemill directory:

./index.js

See the Ubuntu Service page for details about running a headless server without a UI.

Updating

To update your development copy of TileMill clean your copy and rebuild:

# From the `tilemill` directory
git pull
rm -rf node_modules
npm install