How To Use Tugboat to Manage DigitalOcean Droplets from a Terminal
If you are reading this article, then you are probably familiar with how to manage your DigitalOcean droplets from within the Control Panel.
In this guide, we will install and configure Tugboat using an Ubuntu 14.04 VPS. This will act as the "control" droplet for our other DigitalOcean droplets.
Table Of Contents
- How To Install Tugboat
- How To Generate an API Key
- Initial Tugboat Configuration
- Connect to a Droplet
- Droplet Management
- Other Considerations
Log into your new droplet through SSH or by clicking the Console Access button on the droplet page.
Tugboat is a Ruby application, which means that we can install it easily using the RubyGems package manager.
First, we need to install Ruby from Ubuntu's default repositories:
sudo apt-get update sudo apt-get install ruby ruby-dev build-essential
Now, we can install tugboat using RubyGems. We will also install system_timer to avoid a repeated notification message later:
sudo gem install tugboat sudo gem install system_timer
We now have Tugboat installed on our system. Let's set it up.
In order for Tugboat to manage your droplets, you will have to authorize it to access your account through the DigitalOcean API interface. This is a simple procedure.
Log into your account on the DigitalOcean website.
Click on API on the left-hand navigation bar in the Control Panel.
You should see a Client ID pre-populated with a value that references your account.
Below this, if you have not set up an API Key yet, you will be told to generate a key:
Your API key will be generated. Copy this key to a secure location. It will not be available to you again once you click out of this page. You will need to regenerate the key if you lose it.
You need both the Client ID and the API key to configure Tugboat, so keep this window open.
Tugboat includes an initial configuration command that can be called by typing:
You will be asked a series of questions that are necessary to associate tugboat with your DigitalOcean account.
For the first two questions, copy and paste the values from the API page that you have opened:
Enter your client key: Client_ID_from_API_page Enter your API key: API_Key_from_API_page
The next three questions involve the SSH authorization details necessary to connect to all of your droplets.
Press Enter to accept the default SSH key path. Depending on how you usually connect to your other droplets, you may wish to change the SSH user to another value (such as root). Press Enter to accept the default SSH port unless you connect to your droplets using a different port.
Enter your SSH key path (optional, defaults to ~/.ssh/id_rsa): Enter your SSH user (optional, defaults to demo): root Enter your SSH port number (optional, defaults to 22):
Next, you will be taken through the default settings that will be used for new droplet creation. For now, we will press Enter through these prompts to accept the default values.
Enter your default region ID (optional, defaults to 1 (New York)): Enter your default image ID (optional, defaults to 284203 (Ubuntu 12.04 x64)): Enter your default size ID (optional, defaults to 66 (512MB)): Enter your default ssh key ID (optional, defaults to none):
You should receive a reply confirming that your keys were accepted:
Authentication with DigitalOcean was successful.
The selections that we have just made are stored in a hidden file in your home directory called
--- authentication: client_key: xxxxxxxxxxxxxxxxxxxxxx api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx defaults: ssh_key: "" size: "66" image: "284203" region: "1" ssh: ssh_port: "22" ssh_user: root ssh_key_path: /home/demo/.ssh/id_rsa
If you ever need to re-generate your API Key, you will need to change it here after you re-generate it on the DigitalOcean website.
Afterwards, you will want to re-verify that the application can associate correctly by typing:
The SSH section should be self-explanatory if you choose to modify it.
We will cover how to find the information needed to change the defaults section later.
We now have enough configured to explore Tugboat.
Every tugboat command begins with
tugboat followed by an action.
Let's list the droplets that we have in our account:
irssi (ip: xxx.xxx.xxx.xx, status: active, region: 1, id: 3150xx) tug (ip: xxx.xxx.xxx.xxx, status: active, region: 4, id: 3372xx) test (ip: xxx.xxx.xxx.xx, status: active, region: 4, id: 3373xx) DigitalOcean20Dollar (ip: xxx.xxx.xxx.xxx, status: active, region: 4, id: 3520xx) archtestmail (ip: xxx.xxx.xxx.xx, status: active, region: 4, id: 4328xx) TugWrite (ip: xxx.xxx.xxx.xxx, status: active, region: 4, id: 4496xx)
This is analogous to your droplet's screen in the web interface. It lists each droplet that we can interact with.
Let's SSH into one of our droplets by using tugboat:
tugboat ssh ourDroplet
Droplet fuzzy name provided. Finding droplet ID...done, 3150xx (ourDroplet) Executing SSH (ourDroplet)... Warning: Identity file /home/demo/.ssh/id_rsa not accessible: No such file or directory. firstname.lastname@example.org's password:
As you can see, we are asked for the password to
root@ourDroplet. If we had set up SSH keys, we would have been connected without needing any additional interaction.
Exit out of the droplet to get back into the Tugboat droplet.
A feature that is present throughout the Tugboat experience is "Fuzzy name matching". This means that Tugboat will recognize any command that is unambiguous enough.
For instance, we could have reached the same result by typing:
Tugboat will expand
drop to mean
droplets and execute it without any additional input.
This works with droplet names as well.
All of the tasks that you normally accomplish with the Control Panel can be done with Tugboat.
To get more information about a specific droplet, type:
tugboat info droplet_name
Name: irssi ID: 3150xx Status: active IP: xxx.xxx.xxx.xx Region ID: 1 Image ID: 479972 Size ID: 66 Backups Active: false
This is mostly the same information that we are given in-line with the
droplets command, but there are some additional fields, such as the Image ID, Size ID, and whether backups are enabled.
We can control the power-on state of our droplets by issuing the appropriate commands.
To boot a droplet that is currently down, type:
tugboat start droplet_name
To reboot a droplet, type:
tugboat restart droplet_name
To power down a droplet, type:
tugboat halt droplet_name
Droplets can be deleted by simply typing:
tugboat destroy droplet_name
Because this has irreversible consequences, you are asked to confirm the action before the droplet is destroyed:
Droplet fuzzy name provided. Finding droplet ID...done, 4530xx (blahblah) Warning! Potentially destructive action. Please confirm [y/n]:
Type y and Enter to destroy the droplet.
To create a droplet, you can use the following syntax:
tugboat create droplet_name
Without additional arguments, your droplet will be created according to the criteria in the default section of your
We can modify this behavior by passing some optional flags. Use the "help" command with the "create" action as an additional argument to get the usage details of create:
tugboat help create
Usage: tugboat create NAME Options: -k, [--keys=KEYS] # A comma separated list of SSH key ids to add to the droplet -s, [--size=N] # The size_id of the droplet -r, [--region=N] # The region_id of the droplet -i, [--image=N] # The image_id of the droplet Create a droplet.
As you can see, we can embed any of the SSH keys that we have uploaded to the site, and specify the size, region, and base image for the creation process.
We will discuss how to find the appropriate values for these parameters below.
We can choose the settings that we want to use for droplet creation by querying the site for the available options.
To see the list of sizes and their associated IDs, type:
Sizes: 512MB (id: 66) 1GB (id: 63) 2GB (id: 62) 4GB (id: 64) 8GB (id: 65) 16GB (id: 61) 32GB (id: 60) 48GB (id: 70) 64GB (id: 69) 96GB (id: 68)
As you can see, each size is associated with an id, which we use to reference that value.
So if we wanted to create a 2GB droplet, we could issue the following command:
tugboat create -s 62 droplet_name
A similar command is available to see the available regions:
Regions: New York 1 (id: 1) Amsterdam 1 (id: 2) San Francisco 1 (id: 3) New York 2 (id: 4)
Embedding an uploaded SSH key within a new droplet is easy. You can find them by issuing:
SSH Keys: Work key (id: 12345) Home key (id: 56789)
The command to view the available images is slightly more complex, only because by default, it shows the snapshots that you have saved:
My Images: Ubuntu Basic setup (id: 4799xx, distro: Ubuntu) Arch default (id: 4811xx, distro: Arch Linux) LAMP Ubuntu (id: 4908xx, distro: Ubuntu) LAMP Success (id: 5838xx, distro: CentOS)
You can select any of these to use as a base image by using the associated ID.
To get a more complete list, including all of the pre-configured distro and application images, add the global flag:
tugboat images -g
My Images: . . . Global Images: CentOS 5.8 x64 (id: 1601, distro: CentOS) CentOS 5.8 x32 (id: 1602, distro: CentOS) Debian 6.0 x64 (id: 12573, distro: Debian) Debian 6.0 x32 (id: 12575, distro: Debian) . . .
You will see a large list of available images. These are referenced by their ID as well, just like the other settings.
These are the pieces of information that we would need to alter the values of the "default" settings in the
~/.tugboat configuration file.
To take a snapshot using the
snapshot command, type:
tugboat snapshot name_of_snapshot droplet_to_snapshot
To resize a droplet, you need to supply the new size criteria to the
resize command. Your droplet must be powered on to run this successfully:
tugboat resize droplet_name -s size_ID
To reset the root password on a droplet, simply issue the
tugboat password-reset droplet_name
You will receive an email with the new password that has been set for the droplet.
Tugboat includes a great help system. You can access the general help at any time by typing:
This will give you a list of every command that you can use.
To get more fine-grained help, specify a command name after
For instance, to get help with the
authorize command, type:
tugboat help authorize
Like most applications that utilize SSH, Tugboat benefits from properly configured SSH keys.
If you have already created a public and private key pair and uploaded the public key to your DigitalOcean page to use for droplet creation, you can copy the private key to your Tugboat droplet.
To do this, log into the computer that you use to access your DigitalOcean droplets. Change to your ssh configuration directory:
Use scp to copy the private key to the Tugboat droplet:
scp id_rsa tugboat_username@tugboat_droplet_ip:/home/tugboat_username/.ssh/
Log into your Tugboat droplet. Change the ownership of the
id_rsa file to match the username you are using with Tugboat.
sudo chown tugboat_username:tugboat_username ~/.ssh/id_rsa
You should now be able to connect to droplets that have been created with that key without a password:
tugboat ssh example_droplet
Remember to alter your configuration file to use this key for new droplet creation!
If you have not already done so, follow this article to set up key pairs and uploaded a public key to your DigitalOcean page.
One tool that is incredibly useful with Tugboat is
screen, a terminal multiplexer.
Put simply, this tool allows you to manage multiple terminal sessions from a single window. You can create and switch between several "windows", each of which is an independent shell session.
This is especially handy when dealing with multiple SSH sessions, which is exactly what Tugboat allows you to do.
Install screen on Ubuntu by typing:
sudo apt-get update sudo apt-get install screen
Start the application by typing:
You now are using a terminal session that is actually operating within
You can connect to a droplet here by typing:
tugboat ssh droplet1
Now, create a new window by typing:
That is, hold the
control key, and hit the
a key, followed by the
c key. This creates a new window.
Connect to a new droplet in this window by typing:
tugboat ssh droplet2
You can switch between the windows by typing:
You can destroy windows by typing:
Tugboat is a great tool for managing your droplets without ever having to leave a terminal environment. It provides a unified interface to keep track of your droplets and manage your sessions.
Configuring Tugboat correctly eliminates the hassle of having to either perform continuous maintenance on a hosts file or flip back and forth between terminal and browser windows.
If you find any issues with the software or wish to contribute to the project, please visit the Tugboat page on Github.
Thank you Jack Pearkes and the Tugboat team for providing the DigitalOcean community with such a valuable tool!