hdo-0.3: README.md
## HDO: A HAskell Digital Ocean Client ##
[](https://travis-ci.org/capital-match/hdo)
This is a [Digital Ocean](https://www.digitalocean.com/) client written in [Haskell](http://haskell.org). It can be used either as a
library or as command-line utility.
# Build
*hdo* is built with [stack](https://github.com/commercialhaskell/stack/), using [Stackage LTS-7.7](https://www.stackage.org/lts-7.7) dependencies. To build, follow the standard instructions:
Install the correct GHC version:
> stack setup
Build and install the package locally, possibly making executable `docean` available from `PATH`:
> stack install
# Usage
## Command-line Tool
Command-line tool is named `docean`. If it's been installed, it should be available in your PATH. Otherwise, you can run it from the source directory using `stack exec docean -- <args>`. `docean` expects authentication token to be available from environment variable `AUTH_TOKEN`, see [Digital Ocean API](https://developers.digitalocean.com/documentation/v2/#authentication) for details on how to get that authentication token.
> export AUTH_TOKEN=2342342341234eaf
## Available Commands
**NOTE**: Not all the available APIs from DO are implemented (yet).
### Droplets
#### Creating a Droplet
This is the most complex command, as creating a droplet can use a lot of different options.
```
$ docean droplets create -r ams2 -s 1gb -i ubuntu-16-04-x64 -n deploy-test -k '[2436510]'
waiting for droplet deploy-test to become Active: 60s
waiting for droplet deploy-test to become Active: 59s
waiting for droplet deploy-test to become Active: 58s
waiting for droplet deploy-test to become Active: 57s
waiting for droplet deploy-test to become Active: 56s
waiting for droplet deploy-test to become Active: 55s
waiting for droplet deploy-test to become Active: 54s
waiting for droplet deploy-test to become Active: 53s
waiting for droplet deploy-test to become Active: 52s
30876135
deploy-test [Active] ams2: Amsterdam 2
1024M/30G/1 cores
IPv4
95.85.44.239/255.255.255.0 [Public]
IPv6
```
The available parameters are:
* `-r|--region`: Sets the region where droplet is created, using the *region slug*
* `-s|--size`: Sets the size of the droplet, from `512mb` to `96gb`
* `-n|--name`: Name of the newly created droplet
* `-i|--image`: Slug of the image to use as base image for droplet
* `-k|--keys`: List (in the form readable by Haskell to convert to type `[Int]`) of keys to add for accessing the droplet
* `-b|--background`: Create droplet in the background, returning only the identifier of action to be checked later. If not set, creation is *synchronous*: The client will check wait for droplet to be up for 60s.
When successfully created, the main characteristics of the droplet are printed to the console.
#### Other Droplet Operations
Destroy an existing droplet:
```
$ droplets destroy 30876135
-
```
List all created droplets:
```
$ docean droplets list
21002433
droplet-01 [Active] sgp1: Singapore 1
1024M/30G/1 cores
IPv4
1.2.3.4/255.255.240.0 [Public]
IPv6
26082279
droplet-02 [Active] sgp1: Singapore 1
512M/20G/1 cores
IPv4
1.2.3.5/255.255.240.0 [Public]
IPv6
31114780
droplet-03 [Active] ams2: Amsterdam 2
2048M/40G/2 cores
IPv4
5.6.7.8/255.255.240.0 [Public]
IPv6
```
Shutdown/startup a droplet:
```
$ docean droplets power_off 31166171
[163908062] 2016-11-01 21:08:46 UTC -> -
31166171 PowerOff: InProgress
```
```
$ docean droplets power_on 31166171
[163908350] 2016-11-01 21:10:16 UTC -> -
31166171 PowerOn: InProgress
```
Retrieve status of an action initiated on the droplet (usually related to power on/off or snapshots):
```
$ docean droplets action 31166171 163908062
[163908062] 2016-11-01 21:08:46 UTC -> 2016-11-01 21:08:58 UTC
31166171 PowerOff: Completed
```
Take a snapshot of an existing droplet (must be powered off):
```
$ docean droplets snapshot 31166171 mysnapshot
[163908530] 2016-11-01 21:11:19 UTC -> -
31166171 MakeSnapshot: InProgress
```
List existing snapshots for droplet:
```
$ docean droplets 31166171 snapshots
20648640 mysnapshot Ubuntu
```
Connect to the droplet through SSH (can be given a name or a droplet ID):
```
$ docean droplets ssh 31166171
The authenticity of host '1.2.3.4 (1.2.3.4)' can't be established.
RSA key fingerprint is 3f:16:4f:f4:25:85:85:77:1e:90:bd:8c:6b:90:48:eb.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '1.2.3.4' (RSA) to the list of known hosts.
Welcome to Ubuntu 16.04.1 LTS (GNU/Linux 4.4.0-45-generic x86_64)
* Documentation: https://help.ubuntu.com
* Management: https://landscape.canonical.com
* Support: https://ubuntu.com/advantage
0 packages can be updated.
0 updates are security updates.
The programs included with the Ubuntu system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.
Ubuntu comes with ABSOLUTELY NO WARRANTY, to the extent permitted by
applicable law.
root@droplet:~#
```
### Images
### Regions
### Keys
### Sizes
### Floating IPs
### Domains
## Library
TBD