Skip to content


Subversion checkout URL

You can clone with
Download ZIP

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


This document describes the packaging steps for TileMill on Ubuntu.

Debian packages, Launchpad PPA's, and a bit of elbow grease are the tools.


Resources on packaging

These are high level resources you should look at before continuing:

Initial Setup

Install some debian packages:

sudo apt-get install debhelper devscripts dput git-core cdbs pgpgpg

For more info on these requirements see:

Then create your PGP key and upload to launchpad. You can do this through the GUI tool "Passwords and Keys" or using gpg --gen-key.

Make sure to create entropy as the key is created by moving your mouse around or typing.

If you are on a headless server you can fake entropy by using rng-tools and setting your device to /dev/urandom (in /etc/default/rng-tools).

For more info on creating your key see:

Ensure your launchpad user has access to the PPA's at

Instructions for copying packages

The instructions below require copying of packages between PPA's. We do this to ensure proper dependencies (to avoid other PPA updates conflicting with what tilemill needs for versions) and to stage builds for testing.

Here is how to copy packages:

1) Go the the launchpad page for the PPA packages you want to copy from, like:

2) Select the packages you want to copy by checking their box. Confirm the proper package version and include each supported series.

3) Select the Destination PPA. Use MapBox Dev for testing packages. You'll only copy to MapBox when you are ready to publish, and you'll generally want to copy exiting packages from MapBox Dev after testing.

4) The Destination series should be set to The same series.

5) Select Copy existing binaries.

6) Click Copy Packages and wait for the packages to be copied.

Packaging Steps

Build or copy Mapnik packages

Mapnik master is what is usually needed for TileMill releases.

These can either be copied from into the ~developmentseed/mapbox-dev PPA or built and uploaded there directly.

To build them yourself follow the docs at:

Copy nodejs packages

Copy the nodejs packages at the versions that work for TileMill.

Setup TileMill

Locally, on your ubuntu machine checkout TileMill for a given tag:

git clone tilemill-$TAG
cd tilemill-$TAG
git checkout $TAG

Add the PPA dependencies and install them:

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

Now build TileMill:

npm install

Package and upload

Now we need to create a package for every ubuntu distribution and upload it to launchpad.

There is a packaging script located in this directory (./platforms/ubuntu) called which help with this step.

You add a single new changelog entry and then run the script, repeating as many times as distributions you wish to target.

Packaging changes should increment the package version, while upstream source changes should increment the minor/major version. For example package-0.4.0-0ubuntu1 goes to package-0.4.0-0ubuntu2 for packaging changes. For upstream source changes, the minor or major version should change, like package-0.4.1-0ubuntu1. The packaging version always starts at 1.

Edit the changelog:


Note: your changelog name and email must match exactly the name and email you used to create your gpg/pgp keys.

Do not commit this change to the tag, but rather apply it to the master branch of Tilemill.

To create a testing package that will be built and uploaded to "mapbox-dev" PPA do:

cd platforms/ubuntu

Use the -p (production) flag to push a build up to the main "mapbox" PPA:

./ -p


Now, ideally on another machine add the developmentseed/mapbox-dev PPA and test installing tilemill packages. If they work then you can deploy them by copying the packages from the "mapbox-dev" PPA to the "mapbox" PPA.

Testing builds with Pbuilder

If your package depends on other PPA's, as does TileMill and TileStream (nodejs, for example), you can build a pbuilder chroot which will include those PPA's. For example, first use this script in your ~/.pbuilderrc, then, when you create your pbuilder environment, run the command like:

sudo DIST=maverick pbuilder create --override-config --othermirror="\deb maverick main |
deb maverick main"

which will make sure the required PPA's are available within your pbuilder chroot when running test builds. To use this pbuilder, provided you've put the above linked script into ~/.pbuilderrc, just run:

sudo DIST=maverick pbuilder build tilemill_0.4.1-0.dsc
Something went wrong with that request. Please try again.