Installing Paz on Digital Ocean

How to get your Paz cluster in Digital Ocean

Welcome to Paz. By the end of this tutorial you will be running your own installation.


Don't forget

Install Paz Dependencies before continuing


Paz Dashboard

Before you begin - DNS

Before you begin, determine whether or not you want Paz to manage DNS for your services for you (e.g. if your domain is "" then Paz can configure "" when you install a public-facing service called "api" in your cluster and mark it as "public-facing").

If you do want Paz to manage DNS, you will need an account with DNSimple and have a domain ready to be used for your Paz cluster that is managed by DNSimple. You will need the domain name, DNSimple API token and the email address for your DNSimple account. Currently DNSimple is the only service supported by Paz, but expect more to follow.

If you would rather handle this yourself outside of Paz, that is fine, but there are a few things you'll need to understand about how Paz's service discovery and routing work. For that see here.


Register with Digital Ocean and add your SSH key.

Click the "Create Droplet" button in the DigitalOcean console.

Give your droplet a name and choose your droplet size and region.


Creating a Droplet

Tick "Private Networking" and "Enable User Data"

Paste the contents of the digitalocean/userdata file in the paz-sh/paz repository into the userdata text area.

Go to and copy the URL that it prints in the browser, pasting it into the userdata text area instead of the one that is already there.

In the write_files section, in the section for writing the /etc/environment file, edit PAZ_DOMAIN, PAZ_DNSIMPLE_APIKEY and PAZ_DNSIMPLE_EMAIL fields, putting in your DNSimple-managed domain name, DNSimple API key and DNSimple account's email address, respectively.

If you are managing DNS yourself outside of the Paz cluster, set the PAZ_DOMAIN variable, remove the PAZ_DNSIMPLE_* variables and add another: PAZ_ORCHESTRATOR_DNS_DISABLED=true.

  - path: /etc/paz-environment
    permissions: 0644
    content: |
        [email protected]

Before submitting, copy this userdata to a text file or editor because we'll need to use it again unchanged


CoreOS User Data

Select the CoreOS version you want to install. The latest beta version is recommended, as this is the version on which Paz has been tested.

Add the SSH keys that will be added to the box (under core user).


SSH Keys in Digital Ocean

Click "Create Droplet".

Repeat for the number of nodes you want in the cluster (e.g. 3), using the exact same userdata file (i.e. don't generate a new discovery token etc.).

Once all droplets have booted (test by trying to SSH into each one, run docker ps and observe that paz-dnsmasq, cadvisor and paz-haproxy are all running on each box), you may proceed.

The next step is to install Paz on your newly-prepared CoreOS cluster.

From the root directory of the paz-sh/paz repository, type the following:

$ ssh-add ~/.ssh/id_rsa # or equivalent
$ FLEETCTL_TUNNEL=<MACHINE_IP> fleetctl -strict-host-key-checking=false start unitfiles/1/*

...where <MACHINE_IP> is the public IP address of any node in your new CoreOS cluster on DigitalOcean.

This will install the first set of unit files for Paz's internal services. Be patient, this can take 10 minutes or more as it has to pull down some large Docker repositories.

You can wait for all units to be active/running like so:

$ FLEETCTL_TUNNEL=<MACHINE_IP> watch -n 5 fleetctl -strict-host-key-checking=false list-units

Once they're up you can install the final services, which need to be done second because they depend upon the first ones:

$ FLEETCTL_TUNNEL=<MACHINE_IP> fleetctl -strict-host-key-checking=false start unitfiles/2/*

You now have a working Paz installation and you can proceed to run services on it.