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 were 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
admin-team: admin
    user-registration: true
    scheme: native
    url: <your-mongodb-server>:27017
    name: tsurudb
queue: redis
    host: <your-redis-server>
    port: 6379
    unit-repo: /home/application/current
    api-server: http://<your-gandalf-server>:8000
provisioner: docker
    segregate: false
    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
        - http://<your-docker-server>:2375
    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 for the next steps, so we’re going to describe how to install the tsuru-admin and create a new user belonging to the admin team configured in your tsuru.conf file. For a description of each command shown below please refer to the client documentation.

For a description

$ sudo apt-get install tsuru-admin

$ tsuru-admin target-add default http://<your-tsuru-api-addr>:8080
$ tsuru-admin target-set default
$ tsuru-admin user-create myemail@somewhere.com
# type a password and confirmation

$ tsuru-admin login myemail@somewhere.com
# type the chosen password

$ tsuru-admin team-create admin

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

Generating token for Gandalf authentication

Assuming you have already configured your Gandalf server in the previous installation step, 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:

$ tsr 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