Dokku API (Abandoned)

This project is not maintained and considered abandoned. Please consider using Dokku Pro instead.

HTTP API to interact with Dokku Daemon over HTTP.

Requirements

A server running Dokku with Dokku Daemon and Redis, Postgres plugin installed.

How it works?

This is a simple Sinatra app which intereacts with Dokku Daemon's Unix socket. It received the commands and passes it to daemon and saves the result. /var/run/dokku-daemon folder should be mounted into the application so app can access to the socket.

Installing

You need to create an app for the API on the server;

dokku apps:create dokku-api
dokku redis:create dokku-api
dokku postgres:create dokku-api
dokku redis:link dokku-api dokku-api
dokku postgres:link dokku-api dokku-api
dokku storage:mount dokku-api /var/run/dokku-daemon:/var/run/dokku-daemon
dokku ps:scale dokku-api worker=1 

Then you can deploy your app;

git clone https://github.com/dokku/dokku-api
cd dokku-api
git remote add dokku dokku@yourserver.ip:dokku-api
git push dokku

Authentication

Dokku API uses Api-Key and Api-Secret request headers for authentication. Api-Key and Api-Secret headers must be present on all requests.

You can generate a key pair with rake keys:generate command.

dokku run dokku-api rake keys:generate
>   New API key was generated
>   API KEY: b33e456232bba2edb8d5cde370bc2f35 | API SECRET: a46287c12099fdd55f0c9513be0cdb32

Headers

Usage

Retrive all commands

GET /commands

Example

curl -i -H "Api-Key: YOURKEY" -H "Api-Secret: YOURSECRET" http://yourserver.ip:42143/commands

Response

[
  {
    "id": 1,
    "token": "5069a9ff27219462df6743e6a8b635610cd6c6757ca224605713f89d7e3375be",
    "command": "randomcmd",
    "created_at": "2017-03-15T15:13:45+00:00",
    "ran_at": "2017-03-15T15:13:45+00:00",
    "result_data": {
      "ok": false,
      "output": "Invalid command"
    }
  },
  {
    "id": 2,
    "token": "6b0d56b05b5946b5d18c7f8a8891150d52f7e48a354cf8dcd96800b85340dcb3",
    "command": "apps",
    "created_at": "2017-03-15T15:14:47+00:00",
    "ran_at": "2017-03-15T15:14:49+00:00",
    "result_data": {
      "ok": true,
      "output": "=====> My Apps\napi\ndokku-api\nhello_world"
    }
  }
]

Run a command

POST /commands

Adds the given command to the queue and returns the Command as json.

Params

Example

curl -i -X POST -d "cmd=apps" -H "Api-Key: YOURKEY" -H "Api-Secret: YOURSECRET" http://yourserver.ip:42143/commands

Response

  {
    "id": 2,
    "token": "6b0d56b05b5946b5d18c7f8a8891150d52f7e48a354cf8dcd96800b85340dcb3",
    "command": "apps",
    "created_at": "2017-03-15T15:14:47+00:00",
    "ran_at": null,
    "result_data": null
  }

Retrieve a command

GET /commands/:token

Returns the Command with given token

Example

curl -i -H "Api-Key: YOURKEY" -H "Api-Secret: YOURSECRET" http://yourserver.ip:42143/commands/6b0d56b05b5946b5d18c7f8a8891150d52f7e48a354cf8dcd96800b85340dcb3

Params

Response

{
  "id": 3,
  "token": "6b0d56b05b5946b5d18c7f8a8891150d52f7e48a354cf8dcd96800b85340dcb3",
  "command": "apps",
  "created_at": "2017-03-15T15:14:47+00:00",
  "ran_at": "2017-03-15T15:14:49+00:00",
  "result_data": {
    "ok": true,
    "output": "=====> My Apps\napi\ndokku-api\nhello_world"
  }
}

Callbacks

If you pass callback_url parameter when creating a command, dokku-api will send a POST request to the specified URL with the following JSON schema

{
  "id": 3,
  "token": "6b0d56b05b5946b5d18c7f8a8891150d52f7e48a354cf8dcd96800b85340dcb3",
  "command": "apps",
  "created_at": "2017-03-15T15:14:47+00:00",
  "ran_at": "2017-03-15T15:14:49+00:00",
  "result_data": {
    "ok": true,
    "output": "=====> My Apps\napi\ndokku-api\nhello_world"
  }
}

Sidekiq Web

dokku-api uses Sidekiq for background processing. It includes Sidekiq Web UI. To access it you need to set two ENV variables SIDEKIQ_USER and SIDEKIQ_PASSWORD, then you can access it at /sidekiq.