Skip to content
HTTP API on top of Dokku Daemon
Ruby
Branch: master
Clone or download
Pull request Compare This branch is even with dokku:master.
Latest commit 9c47dab Dec 19, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
config
helpers
models
workers
.gitignore
Dockerfile.dev
Gemfile
Gemfile.lock
LICENCE
Procfile
README.MD
Rakefile
app.rb
config.ru
docker-compose.yml

README.MD

Dokku API

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

Name Type Description
Api-Key string Required
Api-Secret string Required

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

Name Type Description
cmd string Required. Command to run.
sync string Optional. true or false Default false. Runs the command synchronously.
callback_url string Optional. The URL to hit after command has been ran

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

Name Type Description
token string Required. Token of the command.

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.

You can’t perform that action at this time.