Version 1

This documentation is for Deis v1 PaaS. For Workflow (v2) documentation visit


In this tutorial, we will show you how to set up your own 3-node cluster on DigitalOcean.

Please get the source and refer to the scripts in contrib/digitalocean while following this documentation.


To complete this guide, you must have the following:

  • A domain to point to the cluster
  • The ability to provision at least 3 DigitalOcean Droplets that are 4GB or greater

Additionally, we’ll need to install Terraform to do the heavy lifting for us.

Check System Requirements

Please refer to System Requirements for resource considerations when choosing a droplet size to run Deis.

Generate SSH Key

The deisctl utility communicates with remote machines over an SSH tunnel. If you don’t already have an SSH key, the following command will generate a new keypair named “deis”:

$ ssh-keygen -q -t rsa -f ~/.ssh/deis -N '' -C deis

Upload this key to DigitalOcean so we can use it for the rest of the provisioning process.

Generate a New Discovery URL

A discovery URL links etcd instances together by storing their peer addresses and metadata under a unique identifier. Run this command from the root of the repository to generate a contrib/coreos/user-data file with a new discovery URL:

$ make discovery-url

Required scripts are supplied in this user-data file, so do not provision a Deis cluster without running make discovery-url.

Create CoreOS Droplets

The only other pieces of information we’ll need are your DigitalOcean API token and the fingerprint of your SSH key, both of which can be obtained from the DigitalOcean interface.

From the source code root directory, invoke Terraform:

$ terraform apply -var 'token=a1b2c3d3e4f5' \
                  -var 'ssh_keys=c1:d3:a2:b4:e4:f5' \
                  -var 'region=nyc3' \
                  -var 'prefix=deis' \
                  -var 'instances=3' \
                  -var 'size=8GB' \

Note that only token and ssh_keys are required - if unset, the other variables will default to 3 hosts in the sfo1 region with a size of 8GB and a prefix of deis. Additionally, ssh_keys can be just one key, or a comma-separated list of keys to be added to the hosts for the core user.

The region option must specify a region with private networking.

Configure DNS


If you’re using your own third-party DNS registrar, please refer to their documentation on this setup, along with the Necessary DNS records required.


If you don’t have an available domain for testing, you can refer to the Using documentation on setting up a wildcard DNS for Deis.

Deis requires a wildcard DNS record to function properly. If the top-level domain (TLD) that you are using is, your applications will exist at the * level. For example, an application called app would be accessible via

One way to configure this on DigitalOcean is to setup round-robin DNS via the DNS control panel. To do this, add the following records to your domain:

  • A wildcard CNAME record at your top-level domain, i.e. a CNAME record with * as the name, and @ as the canonical hostname
  • For each CoreOS machine created, an A-record that points to the TLD, i.e. an A-record named @, with the droplet’s public IP address

The zone file will now have the following entries in it: (your IP addresses will be different)

*   CNAME   @
@   IN A
@   IN A
@   IN A

For convenience, you can also set up DNS records for each node:

deis-1   IN A
deis-2   IN A
deis-3   IN A

If you need help using the DNS control panel, check out this tutorial on DigitalOcean’s community site.

Apply Security Group Settings

Because DigitalOcean does not have a security group feature, we’ll need to add some custom iptables rules so our components are not accessible from the outside world. To do this, there is a script in contrib/ which will help us with that. To run it, use:

$ for i in 1 2 3; do ssh core@deis-$ 'bash -s' < contrib/util/; done

Our components should now be locked down from external sources.

Install Deis Platform

Now that you’ve finished provisioning a cluster, please refer to Install the Deis Platform to start installing the platform.