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. For most users, the installation instructions will be more appropriate.
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, but don’t hesitate to ask for advise in the TileMill support forum.
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.
So far we have working examples of this 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.
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 0.10.0 works best with Mapnik >= 2.1. 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 2.1 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, here are the basics of installing boost on Linux for Mapnik:
# first make sure your have
# python development headers, libbz2, and libicu
# installed, then do:
wget http://voxel.dl.sourceforge.net/project/boost/boost/1.51.0/boost_1_51_0.tar.bz2
tar xjvf boost_1_51_0.tar.bz2
cd boost_1_51_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
./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
sudo ldconfigNow install the other dependencies like boost >= 1.47, 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.
Since Mapnik >= 2.1 is recommended, we will download the 2.1 release and build it from scratch:
wget https://github.com/downloads/mapnik/mapnik/mapnik-v2.1.0.tar.bz2
tar xf mapnik-v2.1.0.tar.bz2
cd mapnik-v2.1.0
./configure && make && sudo make installNext, 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 0.8.8 was the latest release, works well with TileMill 0.10.0, and could be built like:
VERSION="0.8.8"
wget http://nodejs.org/dist/v${VERSION}/node-v${VERSION}.tar.gz
tar xf node-v${VERSION}.tar.gz
cd node-v${VERSION}
./configure && make && sudo make installNow, the last thing before building TileMill itself is to install one more dependency needed just by TileMill, 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
Finally, we are ready to install TileMill master itself:
git clone https://github.com/mapbox/tilemill.git
cd tilemill
npm installIf you hit errors, see the “Troublshooting the npm install step” below but also feel free to ask for help in the TileMill support forum.
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.
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.1.x and Node.js >= 0.6.x (with included npm) are required.
We recommend installing these with the Homebrew package manager, because Homebrew will also make it easier to install their dependencies.
We advise not using the .pkg easy install for Node.js because it will break the builds of several of TileMill’s C++ modules until https://github.com/mapbox/tilemill/issues/1844 is fixed.
After installing Homebrew, install Mapnik and Node.js like:
brew update
brew install mapnik node gitFor more details on Mapnik with Homebrew see the Mapnik wiki.
Then you can download TileMill and install:
git clone https://github.com/mapbox/tilemill.git
cd tilemill
npm installIf you hit errors, see the “Troublshooting the npm install step” below but also feel free to ask for help in the TileMill support forum.
These instructions should work for Ubuntu >= 10.04.
For running the TileMill development version see the instructions at this gist.
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-devThen 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 npmYou 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/mapbox/tilemill.git
cd tilemill
git checkout ${TILEMILL_TAG}
npm installUpon 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. Get in touch and we can help if you provide the exact compile error.
Once the build is complete you can start TileMill with the following command from the tilemill directory:
./index.jsSee the Ubuntu Service page for details about running a headless server without a UI.
To update your development copy of TileMill clean your copy and rebuild:
# From the `tilemill` directory
git pull
rm -rf node_modules
npm install