API Server


tsuru API depends on a MongoDB server, Redis server and Hipache router. Instructions for installing MongoDB and Redis are outside the scope of this documentation, but it’s pretty straight-forward following their docs. installing Hipache is described in other session.

Adding repositories

Let’s start adding the repositories for tsuru.

For debian based distributions (eg. Ubuntu, Debian)

$ curl -s https://packagecloud.io/install/repositories/tsuru/stable/script.deb.sh | sudo bash

For rpm based distributions (eg. RedHat, Fedora)

$ curl -s https://packagecloud.io/install/repositories/tsuru/stable/script.rpm.sh | sudo bash


sudo apt-get install tsuru-server -qqy

Now you need to customize the configuration in the /etc/tsuru/tsuru.conf. A description of possible configuration values can be found in the configuration reference. A basic possible configuration is described below, please note that you should replace the values your-mongodb-server, your-redis-server and your-hipache-server.

listen: ""
debug: true
host: http://<machine-public-addr>:8080 # This port must be the same as in the "listen" conf
repo-manager: none
    user-registration: true
    scheme: native
    url: <your-mongodb-server>:27017
    name: tsurudb
    mongo-url: <your-mongodb-server>:27017
    mongo-database: queuedb
provisioner: docker
    router: hipache
    collection: docker_containers
    repository-namespace: tsuru
    deploy-cmd: /var/lib/tsuru/deploy
        image: tsuru/bs:v1
        reporter-interval: 10
        socket: /var/run/docker.sock
        storage: mongodb
        mongo-url: <your-mongodb-server>:27017
        mongo-database: cluster
        bin: /var/lib/tsuru/start
        port: "8888"
        type: hipache
        domain: <your-hipache-server-ip>.xip.io
        redis-server: <your-redis-server-with-port>

In particular, take note that you must set auth:user-registration to true:

    user-registration: true
    scheme: native

Otherwise, tsuru will fail to create an admin user in the next section.

Now you only need to start your tsuru API server:

sudo sed -i -e 's/=no/=yes/' /etc/default/tsuru-server
sudo start tsuru-server-api

Creating admin user

The creation of an admin user is necessary before interaction with the API is possible. This can be done using the root-user-create command as shown below. This command will create a new authorization role with a global permission allowing this user run any action on tsuru. More fine-grained roles can be created later, please refer to managing users and permissions for more details.

Here we’re also going to describe how to install the tsuru client application. For a description of each command shown below please refer to the client documentation.

For a description

$ tsurud root-user-create [--config <path to tsuru.conf>] myemail@somewhere.com
# type a password and confirmation (only if using native auth scheme)

$ sudo apt-get install tsuru-client
$ sudo yum install tsuru-client

$ tsuru target-add default http://<your-tsuru-api-addr>:8080
$ tsuru target-set default
$ tsuru login myemail@somewhere.com
# type the chosen password

And that’s it, you now have registered a user in your tsuru API server and its ready to run any commands.