Configuring a DigitalOcean droplet

The DigitalOcean droplet integration uses your DigitalOcean API token to access your DigitalOcean account resources (your droplets in this case), and allow you to select them directly from a drop-down in your server configuration.

This allows you to quickly set up your droplets in DeployHQ without the hassle of looking up your droplet name, IP, or username.

The only step required is to create a droplet (if you don’t have an existing one), create a DigitalOcean API token, and to upload your SSH key to the droplet’s .ssh/authorized_keys file, so that DeployHQ can authenticate its connection with the droplet. Let’s go over these step by step.

Pre-requisites

To work this integration, there are some steps that you’ll need to follow to get your setup running. Those are:

• A running droplet on DigitalOcean
• A DigitalOcean API token

Let’s go over these steps one by one!

Create a droplet

To be able to connect DeployHQ to a DigitalOcean droplet, you first need the droplet to exist! So let’s create one. If you already have a running droplet in your environment, feel free to skip this step completely.

First, log in to DigitalOcean, and go into “Droplets” to create your droplet. You can alternatively click on the "Create" button, and select "Droplets" from there.

Once in the droplet configuration page, you’re free to select the options that you deem best for your droplet, such as the most appropriate image for your server, your plan, region, etc. You’re also free to select either password or SSH key as your initial connection authentication method, as we’ll not be using this method through DeployHQ’s integration, and adding our own SSH key manually.

Once all is set as needed, click on “Create droplet” at the bottom of the page, and wait for the droplet to be created and booted up. If you wish to, you can now access the droplet directly from the DigitalOcean’s site to get familiar with its interface and options.

Congrats! You now have your very own droplet to work with.

Create a DigitalOcean API token

Once the droplet is present in your DigitalOcean account, you can then go in the following page: https://cloud.digitalocean.com/account/api/tokens

Here, you’ll be creating a token with which you can authorize our DeployHQ account to access our DigitalOcean resources.

To do so, just click on “Generate new token”, and follow the steps outlined in this new page. You can give the token a name with which to reference it. I recommend a name that will be self-explanatory, as it will help you recognise the token’s objective after some time has passed.

You can also give the token the expiration time most appropriate for you, however, keep in mind that if the token expires, you’ll need to renew it in both DigitalOcean AND DeployHQ to keep the integration running.

As for the token’s scopes, you can either give it full access from the quick select options, or choose droplet >> read + update access, and ssh_keys >> full access if you wish to have a more strict scope for this token.

Once done, you can click on “Generate token”. Now, you should see your token with its personal access token. Be sure to copy it before closing this page, as the token is only shown at this step in the process, and losing it will require you to create a new one once more.

If you wish to know more about how these API tokens work, feel free to take a look in the following documentation.

Adding your DigitalOcean droplet in DeployHQ

Once you have the DigitalOcean API token ready, you can insert it in your DeployHQ account so that you can your droplets available to select instead of adding your droplet parameters manually.

To do so, just go into your DeployHQ project, and create a new server.

Here, select “DigitalOcean” as your protocol, and add your API token. Once added, the “Droplets” drop-down will automatically populate with your existing droplets. Here, select the one you wish to use. Make sure the droplet is running, as stopped droplets will cause a timeout error during DeployHQ’s server creation.

Now, the only missing step is adding your DeployHQ server key to your DigitalOcean droplet, so that DeployHQ’s connection can be authenticated through SSH.

Adding your DeployHQ SSH key in your droplet

The SSH key process normally needs you to generate a new key pair, and store the key pair following the SSH requirements. In this case, however, the key pair is already generated by DeployHQ, so you just need to do the follow-up step, which is to store the public SSH key in your droplet.

To do so, just follow these steps:

• Connect to your droplet’s console.
  • This can be done either through the DigitalOcean dashboard, under your droplet’s “Access” page, or through a regular SSH connection on your local terminal. More info on how to connect to the droplet through SSH can be found here.
• Access your user’s .ssh/authorized_keys file with a file editor, such as nano or vi. Keep in mind that each user on your droplet may have their own .ssh/ folder, located in their respective $HOME paths.
• Add your DeployHQ public key to the authorized_keys ****file in a new line.

• If needed, set your authorized_keys and its .ssh parent folder’s permissions such that they’re accessible. This step might only be needed on your first droplet SSH configuration.

  chmod 700 ~/.ssh
  chmod 600 ~/.ssh/authorized_keys
  

For a more in-depth guide on how to add SSH keys to your existing droplets, feel free to check the following documentation on how to upload your SSH keys to existing DO droplets.

Finishing up the configuration

Once this is done, go back to your DeployHQ server configuration page, select any additional server settings, such as atomic deployments or your server’s environment, and finally, click “Create server”.

And you’re done! Your droplet is added to your DeployHQ server list, and you can start deploying as always.