API Server


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

Adding repositories

Let’s start adding the repositories for tsuru.

sudo apt-get update
sudo apt-get install python-software-properties
sudo apt-add-repository ppa:tsuru/ppa -y
sudo apt-get update


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, your-gandalf-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
    user-registration: true
    scheme: native
    url: <your-mongodb-server>:27017
    name: tsurudb
    redis-host: <your-redis-server>
    redis-port: 6379
    mongo-url: <your-mongodb-server>:27017
    mongo-database: queuedb
    api-server: http://<your-gandalf-server>:8000
provisioner: docker
    router: hipache
    collection: docker_containers
    repository-namespace: tsuru
    deploy-cmd: /var/lib/tsuru/deploy
        storage: mongodb
        mongo-url: <your-mongodb-server>:27017
        mongo-database: cluster
        bin: /var/lib/tsuru/start
        port: "8888"
        add-key-cmd: /var/lib/tsuru/add-key
        user: ubuntu
        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 [--config <path to tsuru.conf>] root-user-create myemail@somewhere.com
# type a password and confirmation (only if using native auth scheme)

$ sudo apt-get 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.

Generating token for Gandalf authentication

Assuming you have already configured your Gandalf server in the previous installation step, now we need to export two extra environment variables to the git user, which will run our deploy hooks, the URL to our API server and a generated token.

First step is to generate a token in the machine we’ve just installed the API server:

$ tsurud token

Now you have to go back to the machine you installed Gandalf, and run this:

$ cat | sudo tee -a /home/git/.bash_profile <<EOF
export TSURU_HOST=http://<your-tsuru-api-addr>:8080
export TSURU_TOKEN=fed1000d6c05019f6550b20dbc3c572996e2c044