Welcome¶

Why tsuru?¶

Docker¶

Docker is an open source project to pack, ship, and run any application as a lightweight, portable, self-sufficient container. When you deploy an app with git push or tsuru app-deploy, tsuru builds a Docker image and then distributes it as units (Docker containers) across your cluster.

Clusters¶

A cluster is a named group of nodes. tsuru API has a scheduler algorithm that distributes applications intelligently across a cluster of nodes.

Nodes¶

A node is a physical or virtual machine with Docker installed.

Applications¶

An application consists of:

• the program’s source code - e.g.: Python, Ruby, Go, PHP, JavaScript, Java, etc.
• an operating system dependencies list – in a file called requirements.apt
• a language-level dependencies list – e.g.: requirements.txt, Gemfile, etc.
• instructions on how to run the program – in a file called Procfile

An application has a name, a unique address, a platform, associated development teams, a repository, and a set of units.

Units¶

A unit is a container. A unit has everything an application needs to run; the fetched operational system and language level dependencies, the application’s source code, the language runtime, and the application’s processes defined in the Procfile.

Platforms¶

A platform is a well-defined pack with installed dependencies for a language or framework that a group of applications will need. A platform might be a container template (Docker image).

For instance, tsuru has a container image for Python applications, with virtualenv installed and other required things needed for tsuru to deploy applications on top of that platform. Platforms are easily extendable and managed by tsuru. Every application runs on top of a platform.

Services¶

A service is a well-defined API that tsuru communicates with to provide extra functionality for applications. Examples of services are MySQL, Redis, MongoDB, etc. tsuru has built-in services, but it is easy to create and add new services to tsuru. Services aren’t managed by tsuru, but by their creators.

API¶

The API component (also referred as the tsuru daemon, or tsurud) is a RESTful API server written with Go. The API is responsible for the deploy workflow and the lifecycle of applications.

Command-line clients and the tsuru dashboard interact with this component.

Database¶

The database component is a MongoDB server.

Queue/Cache¶

The queue and cache component uses Redis.

Gandalf¶

Gandalf is a REST API to manage Git repositories and users and provides access to them over SSH.

Registry¶

The Docker registry is the component responsible for storing and distributing Docker images.

Router¶

The router component routes traffic to application units (Docker containers).

Adding repositories¶

Let’s start adding the repositories for tsuru which contain the Gandalf package.

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

Installing¶

sudo apt-get install gandalf-server

A deploy is executed in the git push. In order to get it working, you will need to add a pre-receive hook. tsuru comes with three pre-receive hooks, all of them need further configuration:

• s3cmd: uses Amazon S3 to store and serve archives
• archive-server: uses tsuru’s archive-server to store and serve archives
• swift: uses Swift to store and serve archives (compatible with Rackspace Cloud Files)

In this documentation, we will use archive-server, but you can use anything that can store a git archive and serve it via HTTP or FTP. You can install archive-server via apt-get too:

sudo apt-get install archive-server

Then you will need to configure Gandalf, install the pre-receive hook, set the proper environment variables and start Gandalf and the archive-server, please note that you should replace the value <your-machine-addr> with your machine public address:

sudo mkdir -p /home/git/bare-template/hooks
sudo curl https://raw.githubusercontent.com/tsuru/tsuru/master/misc/git-hooks/pre-receive.archive-server -o /home/git/bare-template/hooks/pre-receive
sudo chmod +x /home/git/bare-template/hooks/pre-receive
sudo chown -R git:git /home/git/bare-template
cat | sudo tee -a /home/git/.bash_profile <<EOF
export ARCHIVE_SERVER_READ=http://<your-machine-addr>:3232 ARCHIVE_SERVER_WRITE=http://127.0.0.1:3131
EOF

In the /etc/gandalf.conf file, remove the comment from the line “template: /home/git/bare-template”, so it looks like that:

git:
  bare:
    location: /var/lib/gandalf/repositories
    template: /home/git/bare-template

Then start gandalf and archive-server:

sudo start gandalf-server
sudo start archive-server

Configuring tsuru to use Gandalf¶

In order to use Gandalf, you need to change tsuru.conf accordingly:

1. Define “repo-manager” to use “gandalf”;
2. Define “git:api-server” to point to the API of the Gandalf server (example: “http://localhost:8000”);

For more details, please refer to the configuration page.

Token for authentication with tsuru API¶

There is one last step in configuring Gandalf. It involves generating an access token so that the hook we created can access the tsuru API. This must be done after installing the tsuru API and it’s detailed in the next installation step.

Dependencies¶

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

Installing¶

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: "0.0.0.0:8080"
debug: true
host: http://<machine-public-addr>:8080 # This port must be the same as in the "listen" conf
auth:
    user-registration: true
    scheme: native
database:
    url: <your-mongodb-server>:27017
    name: tsurudb
pubsub:
    redis-host: <your-redis-server>
    redis-port: 6379
queue:
    mongo-url: <your-mongodb-server>:27017
    mongo-database: queuedb
git:
    api-server: http://<your-gandalf-server>:8000
provisioner: docker
docker:
    router: hipache
    collection: docker_containers
    repository-namespace: tsuru
    deploy-cmd: /var/lib/tsuru/deploy
    bs:
        image: tsuru/bs:v1
        reporter-interval: 10
        socket: /var/run/docker.sock
    cluster:
        storage: mongodb
        mongo-url: <your-mongodb-server>:27017
        mongo-database: cluster
    run-cmd:
        bin: /var/lib/tsuru/start
        port: "8888"
    ssh:
        add-key-cmd: /var/lib/tsuru/add-key
        user: ubuntu
routers:
    hipache:
        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:

auth:
    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
$ 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
fed1000d6c05019f6550b20dbc3c572996e2c044

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
EOF

Adding repositories¶

Let’s start adding the repositories for tsuru which contain the PlanB package.

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

Installing¶

In order to install PlanB, just use apt-get:

sudo apt-get install planb -y

Configuring¶

You may change the file /etc/default/planb, changing the PLANB_OPTS environment variable for configuring the binding address and the Redis endpoint, along with other settings, as described in PlanB docs.

After changing the file, you only need to start PlanB with:

sudo start planb

Managed nodes¶

First step is configuring your IaaS provider in your tsuru.conf file. Please see the details in IaaS configuration

Assuming you’re using EC2, the configuration will be something like:

iaas:
  default: ec2
  node-protocol: http
  node-port: 2375
  ec2:
    key-id: xxxxxxxxxxx
    secret-key: yyyyyyyyyyyyy

After you have everything configured, adding a new Docker node is done by calling docker-node-add in tsuru-admin command. This command will receive a map of key=value params which are IaaS dependent. A list of possible key params can be seen calling:

$ tsuru-admin docker-node-add iaas=ec2

EC2 IaaS required params:
  image=<image id>         Image AMI ID
  type=<instance type>     Your template uuid

Optional params:
  region=<region>          Chosen region, defaults to us-east-1
  securityGroup=<group>    Chosen security group
  keyName=<key name>       Key name for machine

Every key=value pair will be added as a metadata to the Node and you can send After registering your node, you can list it calling tsuru-admin docker-node-list

$ tsuru-admin docker-node-add iaas=ec2 image=ami-dc5387b4 region=us-east-1 type=m1.small securityGroup=my-sec-group keyName=my-key
Node successfully registered.
$ tsuru-admin docker-node-list
+-------------------------------------------------------+------------+---------+----------------------------+
| Address                                               | IaaS ID    | Status  | Metadata                   |
+-------------------------------------------------------+------------+---------+----------------------------+
| http://ec2-xxxxxxxxxxxxx.compute-1.amazonaws.com:2375 | i-xxxxxxxx | waiting | iaas=ec2                   |
|                                                       |            |         | image=ami-dc5387b4         |
|                                                       |            |         | keyName=my-key             |
|                                                       |            |         | region=us-east-1           |
|                                                       |            |         | securityGroup=my-sec-group |
|                                                       |            |         | type=m1.small              |
+-------------------------------------------------------+------------+---------+----------------------------+

Unmanaged nodes¶

To add a previously provisioned node you call the tsuru-admin docker-node-add with the --register flag and setting the address key with the URL of the Docker API in the remote node and specify the pool of the node with pool=mypoolname.

The docker API must be responding in the referenced address. To instructions about how to install docker on your node, please refer to Docker documentation.

$ tsuru-admin docker-node-add pool=mypoolname --register address=http://node.address.com:2375

Overview¶

If you need a platform that’s not already available in our platforms repository it’s pretty easy to create a new one based on a existing one.

To tsuru to be able to use your platform you only need to have the following scripts available on /var/lib/tsuru:

• /var/lib/tsuru/deploy
• /var/lib/tsuru/start

Using Docker¶

Now we will create a whole new platform with Docker, circus and tsuru basebuilder. tsuru basebuilder provides to us some useful scripts like install, setup and start.

So, using the base platform provided by tsuru we can write a Dockerfile like that:

from ubuntu:14.04
run  apt-get install wget -y --force-yes
run  wget http://github.com/tsuru/basebuilder/tarball/master -O basebuilder.tar.gz --no-check-certificate
run  mkdir /var/lib/tsuru
run  tar -xvf basebuilder.tar.gz -C /var/lib/tsuru --strip 1
run  cp /var/lib/tsuru/base/start /var/lib/tsuru
run  cp /home/your-user/deploy /var/lib/tsuru
run  /var/lib/tsuru/base/install
run  /var/lib/tsuru/base/setup

Adding your platform to tsuru¶

After creating you platform as a Docker image, you can add it to tsuru using tsuru-admin:

$ tsuru-admin platform-add your-platform-name --dockerfile http://url-to-dockerfile

Overview¶

Pool is used by provisioners to group nodes and know if an application can be deployed in these nodes. Users can choose which pool to deploy in tsuru app-create.

Tsuru has three types of pool: team, public and default.

Team’s pool are segregated by teams, and cloud administrator should set teams in this pool manually. This pool are just accessible by team’s members.

Public pools are accessible by any user.

Default pool is where apps are deployed when app’s team owner don’t have a pool associated with it or when app’s creator don’t choose any public pool. Ideally this pool is for experimentation and low profile apps, like service dashboard and “in development” apps. You can just have one default pool. This is the old fallback pool, but with a explicit flag.

$ tsuru-admin pool-add pool1

$ tsuru-admin pool-add pool1 -p

$ tsuru-admin pool-add pool1 -d

$ tsuru-admin pool-add new-default-pool -d -f

$ tsuru-admin pool-teams-add pool1 team1 team2

$ tsuru-admin pool-teams-add pool2 team3

$ tsuru pool-list
+-------+-------------+
| Pools | Teams       |
+-------+-------------+
| pool1 | team1 team2 |
| pool2 | team3       |
+-------+-------------+

$ tsuru-admin pool-remove pool1

$ tsuru-admin pool-teams-remove pool1 team1

$ tsuru-admin pool-teams-remove pool1 team1 team2 team3

Overview¶

tsuru uses schedulers to chooses which node an unit should be deployed. Previously there was a choice between round robin and segregate scheduler. As of 0.11.1, only segregate scheduler is available and it’s the default choice. This change was made because round robin scheduler was broken, unmaintained and was a worse scheduling mechanism than segregate scheduler.

How it works¶

Segregate scheduler is a scheduler that segregates the units among pools.

First, what you need to do is to define a relation between a pool and teams. After that you need to register nodes with the pool metadata information, indicating to which pool the node belongs.

When deploying an application, the scheduler will choose among the nodes within the application pool.

$ tsuru-admin docker-node-add --register address=http://localhost:2375 pool=pool1

How to upgrade Docker with no application downtime¶

A way to upgrade with no downtime is to move all containers from the node that you want to upgrade to another node, upgrade the node and then move the containers back.

You can do it using the command tsuru-admin containers-move:

$ tsuru-admin containers-move <from host> <to host>

Managing SSH public keys¶

In order to be able to send git pushes to the Git server, users need to have their key registered in Gandalf. When Gandalf is enabled, tsuru will enable the usage of three commands for SSH public keys management:

• tsuru key-add
• tsuru key-remove
• tsuru key-list

Each of these commands have a corresponding API endpoint, so other clients of tsuru can also manage keys through the API.

tsuru will not store any public key data, all the data related to SSH keys is handled by Gandalf alone, and when Gandalf is not enabled, those key commands will not work.

Adding Gandalf to an already existing tsuru cluster¶

In the case of an old tsuru cluster running without Gandalf, users and applications registered in tsuru won’t be available in the newly created Gandalf server, or both servers may be out-of-sync.

When Gandalf is enabled, administrators of the cloud can run the tsurud gandalf-sync command.

Concepts¶

Roles¶

To better manage permissions it’s not possible to directly assign permissions to users. First you have to create a role including wanted permissions and then apply this role in regard to a context value to one or more users.

The following commands are available to manage roles and permissions and assign them to users:

• tsuru permission-list
• tsuru role-add
• tsuru role-remove
• tsuru role-list
• tsuru role-permission-add
• tsuru role-permission-remove
• tsuru role-assign
• tsuru role-dissociate
• tsuru role-info

More details about each command can be found in the client documentation.

An example of the typical scenario for adding a new role and assigning it to a user is the following:

$ tsuru role-add app_reader_restarter team
Role successfully created!
$ tsuru role-list
+----------------------+---------+-------------+
| Role                 | Context | Permissions |
+----------------------+---------+-------------+
| AllowAll             | global  | *           |
+----------------------+---------+-------------+
| app_reader_restarter | team    |             |
+----------------------+---------+-------------+
$ tsuru role-permission-add app_reader_restarter app.read app.update.restart
Permission successfully added!
$ tsuru role-list
+----------------------+---------+--------------------+
| Role                 | Context | Permissions        |
+----------------------+---------+--------------------+
| AllowAll             | global  | *                  |
+----------------------+---------+--------------------+
| app_reader_restarter | team    | app.read           |
|                      |         | app.update.restart |
+----------------------+---------+--------------------+
$ tsuru user-list
+-------------------+------------------+-------------+
| User              | Roles            | Permissions |
+-------------------+------------------+-------------+
| admin@example.com | AllowAll(global) | *(global)   |
+-------------------+------------------+-------------+
| myuser@corp.com   |                  |             |
+-------------------+------------------+-------------+
$ tsuru role-assign app_reader_restarter myuser@corp.com myteamname
Role successfully assigned!
$ tsuru user-list
+-------------------+---------------------------------------+-------------------------------------+
| User              | Roles                                 | Permissions                         |
+-------------------+---------------------------------------+-------------------------------------+
| admin@example.com | AllowAll(global)                      | *(global)                           |
+-------------------+---------------------------------------+-------------------------------------+
| myuser@corp.com   | app_reader_restarter(team myteamname) | app.read(team myteamname)           |
|                   |                                       | app.update.restart(team myteamname) |
+-------------------+---------------------------------------+-------------------------------------+

From this moment the user named myuser@corp.com can read and restart all applications belonging to the team named myteamname.

$ tsuru role-default-add --user-create team-creator --team-create team-member

Migrating¶

When you already have an existing tsuru installation it will be necessary to create roles and assign them to all existing users, otherwise they will no longer be able to execute any action in tsuru.

To make this process easier we created a migration to help with the transition. The goal of this migration is to roughly give all existing users the same set of permissions they already had on tsuru. To accomplish this it’ll create 3 different roles: admin, team-member and team-creator.

The admin role will have a global context for the root permission and will be assigned to all users that are members to the admin-team described in tsuru.conf file. This users will be able to do anything, anywhere.

The team-member role will have a team context and the following permissions:

• app
• team
• service-instance

And will be assigned to all users for each team name the user is a member of.

The team-creator role will only include the team.create permission with a global context and will also be assigned to all users.

Also the role team-creator will be assigned as a default role when a new user is created. And the team-member role will be the default role assigned to a user when they create a new team.

Running this migration is optional. If you choose execute it simply run:

$ tsurud [--config <path to tsuru.conf>] migrate --name migrate-roles

Bootstrapping¶

For a new tsuru installation the first user created should have a role with a root permission. To create this user a new command was created in the tsuru daemon application (tsurud) and should be executed right after its installation:

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

bs¶

bs (or big sibling) is a container started automatically by tsuru on every docker node created or registered in tsuru. It’s responsible for reporting information on application containers, this information include metrics, unit status and can also include container logs.

On a default tsuru installation all container started on docker will be configured to send logs to the bs container using the syslog protocol. The bs container will then send the logs to the tsuru api server and to any number of configured external syslog servers. Similar to the diagram below:

Docker Node
+---------------------------------------------------------+       +---------------------+
|                                               syslog    |       |                     |
|                                              +----------------->| ext syslog server 1 |
|  +-----------------+ syslog                  |(optional)|       |                     |
|  |  app container  |+----------+             |          |       +---------------------+
|  +-----------------+           |             +          |
|                                |      +--------------+  |       +---------------------+
|                                +----->|              |syslog    |                     |
|                                       | bs container |+-------->| ext syslog server 2 |
|                                +----->|              |(optional)|                     |
|                                |      +--------------+  |       +---------------------+
|  +-----------------+ syslog    |             +          |
|  |  app container  |+----------+             |          |
|  +-----------------+                         |          |
|                                              |          |
|                                              |          |
|                                              |          |
+----------------------------------------------|----------+
                                               |
                                               |
+-------------------+                          |
|                   |  websocket (optional)    |
| tsuru api server  |<-------------------------+
|                   |
+-------------------+

For informations about how to configure bs to forward logs and also some tunning options, please refer to the bs documentation

The advantage of having the bs container as an intermediary is that it knows how to talk to the tsuru api server. Sending logs to the tsuru api server enables the tsuru app-log command which can be used to quickly troubleshoot problems with the application without the need of a third-party tool to read the logs.

However, tsuru api server is NOT a permanent log storage, only the latest 5000 log lines from each application are stored. If a permanent storage is required an external syslog server must be configured.

Direct¶

tsuru can be configured to completely bypass bs when sending logs. This can be done using the tsuru-admin docker-log-update command. See the command reference documentation for more details.

When a log-driver different from bs is chosen, the logs will be similar to the diagram below:

Docker Node
+-----------------------+
|                       |
|  +-----------------+  |
|  |  app container  |-+|
|  +-----------------+ |chosen driver     +---------------------+
|                      +----------------->|                     |
|                       |                 | external log server |
|                      +----------------->|                     |
|  +-----------------+ |chosen driver     +---------------------+
|  |  app container  |-+|
|  +-----------------+  |
|                       |
+-----------------------+

The downside of using a direct logs is that the tsuru api server will NOT receive any log messages anymore. As a consequence the command tsuru app-log will be disabled and users will have to refer to the chosen log driver to read log messages.

Overview¶

When tsuru API is running slow or hanging, we may want troubleshoot it to discover what is the source of the problem.

One of the ways to debug/troubleshoot the tsuru API is by analyzing the running goroutines.

We may do it by cURL or by sending a USR1 signal.

$ curl -X GET -H "Authorization: bearer <API key>" <tsuru-host>:<port>/debug/goroutines

$ kill -s USR1 <tsurud-PID>

Downloading binaries (Mac OS X, Linux and Windows)¶

We provide pre-built binaries for OS X and Linux, only for the amd64 architecture. You can download these binaries directly from the releases page of the project:

• crane: https://github.com/tsuru/crane/releases
• tsuru: https://github.com/tsuru/tsuru-client/releases
• tsuru-admin: https://github.com/tsuru/tsuru-admin/releases

Using homebrew (Mac OS X only)¶

If you use Mac OS X and homebrew, you may use a custom tap to install tsuru, crane and tsuru-admin. First you need to add the tap:

$ brew tap tsuru/homebrew-tsuru

Now you can install tsuru, tsuru-admin and crane:

$ brew install tsuru
$ brew install tsuru-admin
$ brew install crane

Whenever a new version of any of tsuru’s clients is out, you can just run:

$ brew update
$ brew upgrade <formula> # tsuru/tsuru-admin/crane

For more details on taps, check homebrew documentation.

NOTE: tsuru clients require Go 1.4 or higher. Make sure you have the last version of Go installed in your system.

Using the PPA (Ubuntu only)¶

Ubuntu users can install tsuru clients using apt-get and the tsuru PPA. You’ll need to add the PPA repository locally and run an apt-get update:

$ sudo apt-add-repository ppa:tsuru/ppa
$ sudo apt-get update

Now you can install tsuru’s clients:

$ sudo apt-get install tsuru-client
$ sudo apt-get install crane
$ sudo apt-get install tsuru-admin

Build from source (Linux, Mac OS X and Windows)¶

tsuru’s source is written in Go, so before installing tsuru from source, please make sure you have installed and configured Go.

With Go installed and configured, you can use go get to install any of tsuru’s clients:

$ go get github.com/tsuru/tsuru-client/tsuru
$ go get github.com/tsuru/tsuru-admin
$ go get github.com/tsuru/crane

Install the tsuru client¶

Install the tsuru client for your development platform.

The tsuru client is a command-line tool for creating and managing apps. Check out the CLI usage guide to learn more.

Sign up¶

To create an account, you use the command user-create:

$ tsuru user-create youremail@domain.com

user-create will ask for the desired password twice.

Login¶

To login in tsuru, you use the command login:

$ tsuru login youremail@domain.com

It will ask for your password. Unless your tsuru installation is configured to use OAuth.

Deploy an application¶

Choose from the following getting started tutorials to learn how to deploy your first application using one of the supported platforms:

• Deploying Python applications in tsuru
• Deploying Ruby/Rails applications in tsuru
• Deploying PHP applications in tsuru
• Deploying go applications in tsuru

Overview¶

This document is a hands-on guide to deploying a simple Python application in tsuru. The example application will be a very simple Django project associated to a MySQL service. It’s applicable to any WSGI application.

Creating the app within tsuru¶

To create an app, you use the command app-create:

$ tsuru app-create <app-name> <app-platform>

For Python, the app platform is, guess what, python! Let’s be over creative and develop a never-developed tutorial-app: a blog, and its name will also be very creative, let’s call it “blog”:

$ tsuru app-create blog python

To list all available platforms, use the command platform-list.

You can see all your applications using the command app-list:

$ tsuru app-list
+-------------+-------------------------+--------------------------+
| Application | Units State Summary     | Address                  |
+-------------+-------------------------+--------------------------+
| blog        | 0 of 0 units in-service | blog.192.168.50.4.nip.io |
+-------------+-------------------------+--------------------------+

You can then send the code of your application.

Application code¶

This document will not focus on how to write a Django blog, you can clone the entire source direct from GitHub: https://github.com/tsuru/tsuru-django-sample. Here is what we did for the project:

1. Create the project (django-admin.py startproject)
2. Enable django-admin
3. Install South
4. Create a “posts” app (django-admin.py startapp posts)
5. Add a “Post” model to the app
6. Register the model in django-admin
7. Generate the migration using South

Git deployment¶

When you create a new app, tsuru will display the Git remote that you should use. You can always get it using the command app-info:

$ tsuru app-info --app blog
Application: blog
Repository: git@192.168.50.4.nip.io:blog.git
Platform: python
Teams: admin
Address: blog.192.168.50.4.nip.io
Owner: admin@example.com
Team owner: admin
Deploys: 0
Pool: theonepool

App Plan:
+---------------+--------+------+-----------+--------+---------+
| Name          | Memory | Swap | Cpu Share | Router | Default |
+---------------+--------+------+-----------+--------+---------+
| autogenerated | 0 MB   | 0 MB | 100       |        | false   |
+---------------+--------+------+-----------+--------+---------+

The Git remote will be used to deploy your application using Git. You can just push to tsuru remote and your project will be deployed:

$ git push git@192.168.50.4.nip.io:blog.git master
Counting objects: 119, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (53/53), done.
Writing objects: 100% (119/119), 16.24 KiB, done.
Total 119 (delta 55), reused 119 (delta 55)
remote:
remote:  ---> tsuru receiving push
remote:
remote: From git://cloud.tsuru.io/blog.git
remote:  * branch            master     -> FETCH_HEAD
remote:
remote:  ---> Installing dependencies
#####################################
#          OMIT (see below)         #
#####################################
remote:  ---> Restarting your app
remote:
remote:  ---> Deploy done!
remote:
To git@192.168.50.4.nip.io:blog.git
   a211fba..bbf5b53  master -> master

If you get a “Permission denied (publickey).”, make sure you’re member of a team and have a public key added to tsuru. To add a key, use the command key-add:

$ tsuru key-add mykey ~/.ssh/id_rsa.pub

You can use git remote add to avoid typing the entire remote url every time you want to push:

$ git remote add tsuru git@192.168.50.4.nip.io:blog.git

Then you can run:

$ git push tsuru master
Everything up-to-date

And you will be also able to omit the --app flag from now on:

$ tsuru app-info
Application: blog
Repository: git@192.168.50.4.nip.io:blog.git
Platform: python
Teams: admin
Address: blog.192.168.50.4.nip.io
Owner: admin@example.com
Team owner: admin
Deploys: 0
Pool: theonepool
Units: 1
+------------+---------+
| Unit       | State   |
+------------+---------+
| eab5151eff | started |
+------------+---------+

App Plan:
+---------------+--------+------+-----------+--------+---------+
| Name          | Memory | Swap | Cpu Share | Router | Default |
+---------------+--------+------+-----------+--------+---------+
| autogenerated | 0 MB   | 0 MB | 100       |        | false   |
+---------------+--------+------+-----------+--------+---------+

Listing dependencies¶

In the last section we omitted the dependencies step of deploy. In tsuru, an application can have two kinds of dependencies:

• Operating system dependencies, represented by packages in the package manager of the underlying operating system (e.g.: yum and apt-get);
• Platform dependencies, represented by packages in the package manager of the platform/language (in Python, pip).

All apt-get dependencies must be specified in a requirements.apt file, located in the root of your application, and pip dependencies must be located in a file called requirements.txt, also in the root of the application. Since we will use MySQL with Django, we need to install mysql-python package using pip, and this package depends on two apt-get packages: python-dev and libmysqlclient-dev, so here is how requirements.apt looks like:

libmysqlclient-dev
python-dev

And here is requirements.txt:

Django==1.4.1
MySQL-python==1.2.3
South==0.7.6

Please notice that we’ve included South too, for database migrations, and Django, off-course.

You can see the complete output of installing these dependencies below:

% git push tsuru master
#####################################
#                OMIT               #
#####################################
remote: Reading package lists...
remote: Building dependency tree...
remote: Reading state information...
remote: python-dev is already the newest version.
remote: The following extra packages will be installed:
remote:   libmysqlclient18 mysql-common
remote: The following NEW packages will be installed:
remote:   libmysqlclient-dev libmysqlclient18 mysql-common
remote: 0 upgraded, 3 newly installed, 0 to remove and 0 not upgraded.
remote: Need to get 2360 kB of archives.
remote: After this operation, 9289 kB of additional disk space will be used.
remote: Get:1 http://archive.ubuntu.com/ubuntu/ quantal/main mysql-common all 5.5.27-0ubuntu2 [13.7 kB]
remote: Get:2 http://archive.ubuntu.com/ubuntu/ quantal/main libmysqlclient18 amd64 5.5.27-0ubuntu2 [949 kB]
remote: Get:3 http://archive.ubuntu.com/ubuntu/ quantal/main libmysqlclient-dev amd64 5.5.27-0ubuntu2 [1398 kB]
remote: debconf: unable to initialize frontend: Dialog
remote: debconf: (Dialog frontend will not work on a dumb terminal, an emacs shell buffer, or without a controlling terminal.)
remote: debconf: falling back to frontend: Readline
remote: debconf: unable to initialize frontend: Readline
remote: debconf: (This frontend requires a controlling tty.)
remote: debconf: falling back to frontend: Teletype
remote: dpkg-preconfigure: unable to re-open stdin:
remote: Fetched 2360 kB in 1s (1285 kB/s)
remote: Selecting previously unselected package mysql-common.
remote: (Reading database ... 23143 files and directories currently installed.)
remote: Unpacking mysql-common (from .../mysql-common_5.5.27-0ubuntu2_all.deb) ...
remote: Selecting previously unselected package libmysqlclient18:amd64.
remote: Unpacking libmysqlclient18:amd64 (from .../libmysqlclient18_5.5.27-0ubuntu2_amd64.deb) ...
remote: Selecting previously unselected package libmysqlclient-dev.
remote: Unpacking libmysqlclient-dev (from .../libmysqlclient-dev_5.5.27-0ubuntu2_amd64.deb) ...
remote: Setting up mysql-common (5.5.27-0ubuntu2) ...
remote: Setting up libmysqlclient18:amd64 (5.5.27-0ubuntu2) ...
remote: Setting up libmysqlclient-dev (5.5.27-0ubuntu2) ...
remote: Processing triggers for libc-bin ...
remote: ldconfig deferred processing now taking place
remote: sudo: Downloading/unpacking Django==1.4.1 (from -r /home/application/current/requirements.txt (line 1))
remote:   Running setup.py egg_info for package Django
remote:
remote: Downloading/unpacking MySQL-python==1.2.3 (from -r /home/application/current/requirements.txt (line 2))
remote:   Running setup.py egg_info for package MySQL-python
remote:
remote:     warning: no files found matching 'MANIFEST'
remote:     warning: no files found matching 'ChangeLog'
remote:     warning: no files found matching 'GPL'
remote: Downloading/unpacking South==0.7.6 (from -r /home/application/current/requirements.txt (line 3))
remote:   Running setup.py egg_info for package South
remote:
remote: Installing collected packages: Django, MySQL-python, South
remote:   Running setup.py install for Django
remote:     changing mode of build/scripts-2.7/django-admin.py from 644 to 755
remote:
remote:     changing mode of /usr/local/bin/django-admin.py to 755
remote:   Running setup.py install for MySQL-python
remote:     building '_mysql' extension
remote:     gcc -pthread -fno-strict-aliasing -DNDEBUG -g -fwrapv -O2 -Wall -Wstrict-prototypes -fPIC -Dversion_info=(1,2,3,'final',0) -D__version__=1.2.3 -I/usr/include/mysql -I/usr/include/python2.7 -c _mysql.c -o build/temp.linux-x86_64-2.7/_mysql.o -DBIG_JOINS=1 -fno-strict-aliasing -g
remote:     In file included from _mysql.c:36:0:
remote:     /usr/include/mysql/my_config.h:422:0: warning: "HAVE_WCSCOLL" redefined [enabled by default]
remote:     In file included from /usr/include/python2.7/Python.h:8:0,
remote:                      from pymemcompat.h:10,
remote:                      from _mysql.c:29:
remote:     /usr/include/python2.7/pyconfig.h:890:0: note: this is the location of the previous definition
remote:     gcc -pthread -shared -Wl,-O1 -Wl,-Bsymbolic-functions -Wl,-Bsymbolic-functions -Wl,-z,relro build/temp.linux-x86_64-2.7/_mysql.o -L/usr/lib/x86_64-linux-gnu -lmysqlclient_r -lpthread -lz -lm -lrt -ldl -o build/lib.linux-x86_64-2.7/_mysql.so
remote:
remote:     warning: no files found matching 'MANIFEST'
remote:     warning: no files found matching 'ChangeLog'
remote:     warning: no files found matching 'GPL'
remote:   Running setup.py install for South
remote:
remote: Successfully installed Django MySQL-python South
remote: Cleaning up...
#####################################
#                OMIT               #
#####################################
To git@192.168.50.4.nip.io:blog.git
   a211fba..bbf5b53  master -> master

Running the application¶

As you can see, in the deploy output there is a step described as “Restarting your app”. In this step, tsuru will restart your app if it’s running, or start it if it’s not. But how does tsuru start an application? That’s very simple, it uses a Procfile (a concept stolen from Foreman). In this Procfile, you describe how your application should be started. We can use gunicorn, for example, to start our Django application. Here is how the Procfile should look like:

web: gunicorn -b 0.0.0.0:$PORT blog.wsgi

Now we commit the file and push the changes to tsuru git server, running another deploy:

$ git add Procfile
$ git commit -m "Procfile: added file"
$ git push tsuru master
Counting objects: 5, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 326 bytes, done.
Total 3 (delta 1), reused 0 (delta 0)
remote:
remote:  ---> tsuru receiving push
remote:
remote:  ---> Installing dependencies
remote: Reading package lists...
remote: Building dependency tree...
remote: Reading state information...
remote: python-dev is already the newest version.
remote: libmysqlclient-dev is already the newest version.
remote: 0 upgraded, 0 newly installed, 0 to remove and 1 not upgraded.
remote: Requirement already satisfied (use --upgrade to upgrade): Django==1.4.1 in /usr/local/lib/python2.7/dist-packages (from -r /home/application/current/requirements.txt (line 1))
remote: Requirement already satisfied (use --upgrade to upgrade): MySQL-python==1.2.3 in /usr/local/lib/python2.7/dist-packages (from -r /home/application/current/requirements.txt (line 2))
remote: Requirement already satisfied (use --upgrade to upgrade): South==0.7.6 in /usr/local/lib/python2.7/dist-packages (from -r /home/application/current/requirements.txt (line 3))
remote: Cleaning up...
remote:
remote:  ---> Restarting your app
remote: /var/lib/tsuru/hooks/start: line 13: gunicorn: command not found
remote:
remote:  ---> Deploy done!
remote:
To git@192.168.50.4.nip.io:blog.git
   81e884e..530c528  master -> master

Now we get an error: gunicorn: command not found. It means that we need to add gunicorn to requirements.txt file:

$ cat >> requirements.txt
gunicorn==0.14.6
^D

Now we commit the changes and run another deploy:

$ git add requirements.txt
$ git commit -m "requirements.txt: added gunicorn"
$ git push tsuru master
Counting objects: 5, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 325 bytes, done.
Total 3 (delta 1), reused 0 (delta 0)
remote:
remote:  ---> tsuru receiving push
remote:
[...]
remote:  ---> Restarting your app
remote:
remote:  ---> Deploy done!
remote:
To git@192.168.50.4.nip.io:blog.git
   530c528..542403a  master -> master

Now that the app is deployed, you can access it from your browser, getting the IP or host listed in app-list and opening it. For example, in the list below:

$ tsuru app-list
+-------------+-------------------------+---------------------+
| Application | Units State Summary     | Address             |
+-------------+-------------------------+---------------------+
| blog        | 1 of 1 units in-service | blog.cloud.tsuru.io |
+-------------+-------------------------+---------------------+

We can access the admin of the app in the URL http://blog.cloud.tsuru.io/admin/.

Deployment hooks¶

It would be boring to manually run syncdb and/or migrate after every deployment. So we can configure an automatic hook to always run before or after the app restarts.

tsuru parses a file called tsuru.yaml and runs restart hooks. As the extension suggests, this is a YAML file, that contains a list of commands that should run before and after the restart. Here is our example of tsuru.yaml:

hooks:
  build:
    - python manage.py syncdb --noinput
    - python manage.py migrate

For more details, check the hooks documentation.

tsuru will look for the file in the root of the project. Let’s commit and deploy it:

$ git add tsuru.yaml
$ git commit -m "tsuru.yaml: added file"
$ git push tsuru master
Counting objects: 4, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 338 bytes, done.
Total 3 (delta 1), reused 0 (delta 0)
remote:
remote:  ---> tsuru receiving push
remote:
remote:  ---> Installing dependencies
remote: Reading package lists...
remote: Building dependency tree...
remote: Reading state information...
remote: python-dev is already the newest version.
remote: libmysqlclient-dev is already the newest version.
remote: 0 upgraded, 0 newly installed, 0 to remove and 15 not upgraded.
remote: Requirement already satisfied (use --upgrade to upgrade): Django==1.4.1 in /usr/local/lib/python2.7/dist-packages (from -r /home/application/current/requirements.txt (line 1))
remote: Requirement already satisfied (use --upgrade to upgrade): MySQL-python==1.2.3 in /usr/local/lib/python2.7/dist-packages (from -r /home/application/current/requirements.txt (line 2))
remote: Requirement already satisfied (use --upgrade to upgrade): South==0.7.6 in /usr/local/lib/python2.7/dist-packages (from -r /home/application/current/requirements.txt (line 3))
remote: Requirement already satisfied (use --upgrade to upgrade): gunicorn==0.14.6 in /usr/local/lib/python2.7/dist-packages (from -r /home/application/current/requirements.txt (line 4))
remote: Cleaning up...
remote:
remote:  ---> Restarting your app
remote:
remote:  ---> Running restart:after
remote:
remote:  ---> Deploy done!
remote:
To git@192.168.50.4.nip.io:blog.git
   a780de9..1b675b8  master -> master

It’s done! Now we have a Django project deployed on tsuru, using a MySQL service.

Going further¶

For more information, you can dig into tsuru docs, or read complete instructions of use for the tsuru command.

Overview¶

This document is a hands-on guide to deploying a simple Ruby application in tsuru. The example application will be a very simple Rails project associated to a MySQL service.

Creating the app within tsuru¶

To create an app, you use the command app-create:

$ tsuru app-create <app-name> <app-platform>

For Ruby, the app platform is ruby! Let’s be over creative and develop a never-developed tutorial-app: a blog, and its name will also be very creative, let’s call it “blog”:

$ tsuru app-create blog ruby

To list all available platforms, use the command platform-list.

You can see all your applications using the command app-list:

$ tsuru app-list
+-------------+-------------------------+-------------+
| Application | Units State Summary     | Address     |
+-------------+-------------------------+-------------+
| blog        | 0 of 0 units in-service |             |
+-------------+-------------------------+-------------+

Application code¶

This document will not focus on how to write a blog with Rails, you can clone the entire source direct from GitHub: https://github.com/tsuru/tsuru-ruby-sample. Here is what we did for the project:

1. Create the project (rails new blog)
2. Generate the scaffold for Post (rails generate scaffold Post title:string body:text)

Git deployment¶

When you create a new app, tsuru will display the Git remote that you should use. You can always get it using the command app-info:

$ tsuru app-info --app blog
Application: blog
Repository: git@192.168.50.4.nip.io:blog.git
Platform: ruby
Teams: admin
Address: blog.192.168.50.4.nip.io
Owner: admin@example.com
Team owner: admin
Deploys: 0
Pool: theonepool

App Plan:
+---------------+--------+------+-----------+--------+---------+
| Name          | Memory | Swap | Cpu Share | Router | Default |
+---------------+--------+------+-----------+--------+---------+
| autogenerated | 0 MB   | 0 MB | 100       |        | false   |
+---------------+--------+------+-----------+--------+---------+

The Git remote will be used to deploy your application using Git. You can just push to tsuru remote and your project will be deployed:

$ git push git@192.168.50.4.nip.io:blog.git master
Counting objects: 86, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (75/75), done.
Writing objects: 100% (86/86), 29.75 KiB, done.
Total 86 (delta 2), reused 0 (delta 0)
remote: Cloning into '/home/application/current'...
remote: requirements.apt not found.
remote: Skipping...
remote: /home/application/current /
remote: Fetching gem metadata from https://rubygems.org/.........
remote: Fetching gem metadata from https://rubygems.org/..
#####################################
#          OMIT (see below)         #
#####################################
remote:  ---> App will be restarted, please check its log for more details...
remote:
To git@192.168.50.4.nip.io:blog.git
 * [new branch]      master -> master

If you get a “Permission denied (publickey).”, make sure you’re member of a team and have a public key added to tsuru. To add a key, use the command key-add:

$ tsuru key-add mykey ~/.ssh/id_rsa.pub

You can use git remote add to avoid typing the entire remote url every time you want to push:

$ git remote add tsuru git@192.168.50.4.nip.io:blog.git

Then you can run:

$ git push tsuru master
Everything up-to-date

And you will be also able to omit the --app flag from now on:

$ tsuru app-info
Application: blog
Repository: git@192.168.50.4.nip.io:blog.git
Platform: ruby
Teams: admin
Address: blog.192.168.50.4.nip.io
Owner: admin@example.com
Team owner: admin
Deploys: 0
Pool: theonepool
Units: 1
+------------+---------+
| Unit       | State   |
+------------+---------+
| eab5151eff | started |
+------------+---------+

App Plan:
+---------------+--------+------+-----------+--------+---------+
| Name          | Memory | Swap | Cpu Share | Router | Default |
+---------------+--------+------+-----------+--------+---------+
| autogenerated | 0 MB   | 0 MB | 100       |        | false   |
+---------------+--------+------+-----------+--------+---------+

Listing dependencies¶

In the last section we omitted the dependencies step of deploy. In tsuru, an application can have two kinds of dependencies:

• Operating system dependencies, represented by packages in the package manager of the underlying operating system (e.g.: yum and apt-get);
• Platform dependencies, represented by packages in the package manager of the platform/language (in Ruby, bundler).

All apt-get dependencies must be specified in a requirements.apt file, located in the root of your application, and ruby dependencies must be located in a file called Gemfile, also in the root of the application. Since we will use MySQL with Rails, we need to install mysql package using gem, and this package depends on an apt-get package: libmysqlclient-dev, so here is how requirements.apt looks like:

libmysqlclient-dev

And here is Gemfile:

source 'https://rubygems.org'

gem 'rails', '3.2.13'
gem 'mysql'
gem 'sass-rails',   '~> 3.2.3'
gem 'coffee-rails', '~> 3.2.1'
gem 'therubyracer', platforms: 'ruby'
gem 'uglifier', '>= 1.0.3'
gem 'jquery-rails'

You can see the complete output of installing these dependencies below:

$ git push tsuru master
#####################################
#                OMIT               #
#####################################
remote: Reading package lists...
remote: Building dependency tree...
remote: Reading state information...
remote: The following extra packages will be installed:
remote:   libmysqlclient18 mysql-common
remote: The following NEW packages will be installed:
remote:   libmysqlclient-dev libmysqlclient18 mysql-common
remote: 0 upgraded, 3 newly installed, 0 to remove and 0 not upgraded.
remote: Need to get 2360 kB of archives.
remote: After this operation, 9289 kB of additional disk space will be used.
remote: Get:1 http://archive.ubuntu.com/ubuntu/ quantal/main mysql-common all 5.5.27-0ubuntu2 [13.7 kB]
remote: Get:2 http://archive.ubuntu.com/ubuntu/ quantal/main libmysqlclient18 amd64 5.5.27-0ubuntu2 [949 kB]
remote: Get:3 http://archive.ubuntu.com/ubuntu/ quantal/main libmysqlclient-dev amd64 5.5.27-0ubuntu2 [1398 kB]
remote: Fetched 2360 kB in 2s (1112 kB/s)
remote: Selecting previously unselected package mysql-common.
remote: (Reading database ... 41063 files and directories currently installed.)
remote: Unpacking mysql-common (from .../mysql-common_5.5.27-0ubuntu2_all.deb) ...
remote: Selecting previously unselected package libmysqlclient18:amd64.
remote: Unpacking libmysqlclient18:amd64 (from .../libmysqlclient18_5.5.27-0ubuntu2_amd64.deb) ...
remote: Selecting previously unselected package libmysqlclient-dev.
remote: Unpacking libmysqlclient-dev (from .../libmysqlclient-dev_5.5.27-0ubuntu2_amd64.deb) ...
remote: Setting up mysql-common (5.5.27-0ubuntu2) ...
remote: Setting up libmysqlclient18:amd64 (5.5.27-0ubuntu2) ...
remote: Setting up libmysqlclient-dev (5.5.27-0ubuntu2) ...
remote: Processing triggers for libc-bin ...
remote: ldconfig deferred processing now taking place
remote: /home/application/current /
remote: Fetching gem metadata from https://rubygems.org/..........
remote: Fetching gem metadata from https://rubygems.org/..
remote: Using rake (10.1.0)
remote: Using i18n (0.6.1)
remote: Using multi_json (1.7.8)
remote: Using activesupport (3.2.13)
remote: Using builder (3.0.4)
remote: Using activemodel (3.2.13)
remote: Using erubis (2.7.0)
remote: Using journey (1.0.4)
remote: Using rack (1.4.5)
remote: Using rack-cache (1.2)
remote: Using rack-test (0.6.2)
remote: Using hike (1.2.3)
remote: Using tilt (1.4.1)
remote: Using sprockets (2.2.2)
remote: Using actionpack (3.2.13)
remote: Using mime-types (1.23)
remote: Using polyglot (0.3.3)
remote: Using treetop (1.4.14)
remote: Using mail (2.5.4)
remote: Using actionmailer (3.2.13)
remote: Using arel (3.0.2)
remote: Using tzinfo (0.3.37)
remote: Using activerecord (3.2.13)
remote: Using activeresource (3.2.13)
remote: Using coffee-script-source (1.6.3)
remote: Using execjs (1.4.0)
remote: Using coffee-script (2.2.0)
remote: Using rack-ssl (1.3.3)
remote: Using json (1.8.0)
remote: Using rdoc (3.12.2)
remote: Using thor (0.18.1)
remote: Using railties (3.2.13)
remote: Using coffee-rails (3.2.2)
remote: Using jquery-rails (3.0.4)
remote: Installing libv8 (3.11.8.17)
remote: Installing mysql (2.9.1)
remote: Using bundler (1.3.5)
remote: Using rails (3.2.13)
remote: Installing ref (1.0.5)
remote: Using sass (3.2.10)
remote: Using sass-rails (3.2.6)
remote: Installing therubyracer (0.11.4)
remote: Installing uglifier (2.1.2)
remote: Your bundle is complete!
remote: Gems in the groups test and development were not installed.
remote: It was installed into ./vendor/bundle
#####################################
#                OMIT               #
#####################################
To git@192.168.50.4.nip.io:blog.git
   9515685..d67c3cd  master -> master

Running the application¶

As you can see, in the deploy output there is a step described as “Restarting your app”. In this step, tsuru will restart your app if it’s running, or start it if it’s not. But how does tsuru start an application? That’s very simple, it uses a Procfile (a concept stolen from Foreman). In this Procfile, you describe how your application should be started. Here is how the Procfile should look like:

web: bundle exec rails server -p $PORT -e production

Now we commit the file and push the changes to tsuru Git server, running another deploy:

$ git add Procfile
$ git commit -m "Procfile: added file"
$ git push tsuru master
#####################################
#                OMIT               #
#####################################
remote:  ---> App will be restarted, please check its log for more details...
remote:
To git@192.168.50.4.nip.io:blog.git
   d67c3cd..f2a5d2d  master -> master

Now that the app is deployed, you can access it from your browser, getting the IP or host listed in app-list and opening it. For example, in the list below:

$ tsuru app-list
+-------------+-------------------------+---------------------+
| Application | Units State Summary     | Address             |
+-------------+-------------------------+---------------------+
| blog        | 1 of 1 units in-service | blog.cloud.tsuru.io |
+-------------+-------------------------+---------------------+

Deployment hooks¶

It would be boring to manually run rake db:migrate after every deployment. So we can configure an automatic hook to always run before or after the app restarts.

tsuru parses a file called tsuru.yaml and runs restart hooks. As the extension suggests, this is a YAML file, that contains a list of commands that should run before and after the restart. Here is our example of tsuru.yaml:

hooks:
  restart:
    before:
      - RAILS_ENV=production bundle exec rake db:migrate

For more details, check the hooks documentation.

tsuru will look for the file in the root of the project. Let’s commit and deploy it:

$ git add tsuru.yaml
$ git commit -m "tsuru.yaml: added file"
$ git push tsuru master
#####################################
#                OMIT               #
#####################################
To git@192.168.50.4.nip.io:blog.git
   a780de9..1b675b8  master -> master

It is necessary to compile de assets before the app restart. To do it we can use the rake assets:precompile command. Then let’s add the command to compile the assets in tsuru.yaml:

hooks:
  build:
    - RAILS_ENV=production bundle exec rake assets:precompile

$ git add tsuru.yaml
$ git commit -m "tsuru.yaml: added file"
$ git push tsuru master
#####################################
#                OMIT               #
#####################################
To git@192.168.50.4.nip.io:blog.git
   a780de9..1b675b8  master -> master

It’s done! Now we have a Rails project deployed on tsuru.

Now we can access your blog app in the URL returned in app-info.

Going further¶

For more information, you can dig into the tsuru docs, or read the complete instructions on how to use the tsuru command.

Overview¶

This document is a hands-on guide to deploying a simple Go web application in tsuru.

Creating the app within tsuru¶

To create an app, you use the command app-create:

$ tsuru app-create <app-name> <app-platform>

For Go, the platform name is go! Let’s be over creative and develop a hello world tutorial-app, let’s call it “helloworld”:

$ tsuru app-create helloworld go

To list all available platforms, use the command platform-list.

You can see all your applications using the command app-list:

$ tsuru app-list
+-------------+-------------------------+--------------------------------+
| Application | Units State Summary     | Address                        |
+-------------+-------------------------+--------------------------------+
| helloworld  | 0 of 0 units in-service | helloworld.192.168.50.4.nip.io |
+-------------+-------------------------+--------------------------------+

Application code¶

A simple web application in Go main.go:

package main

import (
    "fmt"
    "net/http"
    "os"
)

func main() {
    http.HandleFunc("/", hello)
    fmt.Println("listening...")
    err := http.ListenAndServe(":" + os.Getenv("PORT"), nil)
    if err != nil {
        panic(err)
    }
}

func hello(res http.ResponseWriter, req *http.Request) {
    fmt.Fprintln(res, "hello, world!")
}

Git deployment¶

When you create a new app, tsuru will display the Git remote that you should use. You can always get it using the command app-info:

$ tsuru app-info --app helloworld
Application: helloworld
Repository: git@192.168.50.4.nip.io:helloworld.git
Platform: go
Teams: admin
Address: helloworld.192.168.50.4.nip.io
Owner: admin@example.com
Team owner: admin
Deploys: 0
Pool: theonepool

App Plan:
+---------------+--------+------+-----------+--------+---------+
| Name          | Memory | Swap | Cpu Share | Router | Default |
+---------------+--------+------+-----------+--------+---------+
| autogenerated | 0 MB   | 0 MB | 100       |        | false   |
+---------------+--------+------+-----------+--------+---------+

The git remote will be used to deploy your application using git. You can just push to tsuru remote and your project will be deployed:

$ git push git@192.168.50.4.nip.io:helloworld.git master
Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 430 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
remote: tar: Removing leading `/' from member names
remote: /
remote:
remote: ---- Building application image ----
remote:  ---> Sending image to repository (5.57MB)
remote:  ---> Cleaning up
remote:
remote: ---- Starting 1 new unit ----
remote:  ---> Started unit b21298a64e...
remote:
remote: ---- Binding and checking 1 new units ----
remote:  ---> Bound and checked unit b21298a64e
remote:
remote: ---- Adding routes to 1 new units ----
remote:  ---> Added route to unit b21298a64e
remote:
remote: OK
To git@192.168.50.4.nip.io:helloworld.git
 * [new branch]      master -> master

If you get a “Permission denied (publickey).”, make sure you’re member of a team and have a public key added to tsuru. To add a key, use the command key-add:

$ tsuru key-add mykey ~/.ssh/id_rsa.pub

You can use git remote add to avoid typing the entire remote url every time you want to push:

$ git remote add tsuru git@192.168.50.4.nip.io:helloworld.git

Then you can run:

$ git push tsuru master
Everything up-to-date

And you will be also able to omit the --app flag from now on:

$ tsuru app-info
Application: helloworld
Repository: git@192.168.50.4.nip.io:helloworld.git
Platform: go
Teams: admin
Address: helloworld.192.168.50.4.nip.io
Owner: admin@example.com
Team owner: admin
Deploys: 1
Pool: theonepool
Units: 1
+------------+---------+
| Unit       | State   |
+------------+---------+
| b21298a64e | started |
+------------+---------+

App Plan:
+---------------+--------+------+-----------+--------+---------+
| Name          | Memory | Swap | Cpu Share | Router | Default |
+---------------+--------+------+-----------+--------+---------+
| autogenerated | 0 MB   | 0 MB | 100       |        | false   |
+---------------+--------+------+-----------+--------+---------+

Running the application¶

tsuru will compile and run the application automatically, but it’s possible to customize how tsuru compiles and runs the application. For more details, check the README of the Go platform: https://github.com/tsuru/basebuilder/blob/master/go/README.md.

Now that the app is deployed, you can access it from your browser, getting the IP or host listed in app-list and opening it. For example, in the list below:

$ tsuru app-list
+-------------+-------------------------+--------------------------------+
| Application | Units State Summary     | Address                        |
+-------------+-------------------------+--------------------------------+
| helloworld  | 1 of 1 units in-service | helloworld.192.168.50.4.nip.io |
+-------------+-------------------------+--------------------------------+

It’s done! Now we have a simple go project deployed on tsuru.

Now we can access your app in the URL displayed in app-list (“helloworld.192.168.50.4.nip.io” in this case).

Going further¶

For more information, you can dig into tsuru docs, or read complete instructions of use for the tsuru command.

Overview¶

This document is a hands-on guide to deploying a simple Java application on tsuru. The example application is a simple mvn generated archetype, in order to generate it, just run:

$ mvn archetype:generate -DgroupId=io.tsuru.javasample -DartifactId=helloweb -DarchetypeArtifactId=maven-archetype-webapp

You can also deploy any other Java application you have on a tsuru server. Another alternative is to just download the code available at GitHub: https://github.com/tsuru/tsuru-java-sample.

Creating the app within tsuru¶

To create an app, you use the command app-create:

$ tsuru app-create <app-name> <app-platform>

For Java, the app platform is, guess what, java! Let’s call our application “helloweb”:

$ tsuru app-create helloweb java

To list all available platforms, use the command platform-list.

You can see all your applications using the command app-list:

$ tsuru app-list
+-------------+-------------------------+------------------------------+
| Application | Units State Summary     | Address                      |
+-------------+-------------------------+------------------------------+
| helloweb    | 0 of 0 units in-service | helloweb.192.168.50.4.nip.io |
+-------------+-------------------------+------------------------------+

Deploying the code¶

Using the Java platform, there are two deployment strategies: users can either upload WAR files to tsuru or send the code using the regular git push approach. This guide will cover both approaches:

$ mvn package
$ cd target
$ tsuru app-deploy -a helloweb helloweb.war
Uploading files.... ok

---- Building application image ----
 ---> Sending image to repository (0.00MB)
 ---> Cleaning up

---- Starting 1 new unit ----
 ---> Started unit 21c3b6aafa...

---- Binding and checking 1 new units ----
 ---> Bound and checked unit 21c3b6aafa

---- Adding routes to 1 new units ----
 ---> Added route to unit 21c3b6aafa

OK

$ mv helloweb.war ROOT.war
$ tsuru app-deploy -a helloweb ROOT.war
Uploading files... ok

---- Building application image ----
 ---> Sending image to repository (0.00MB)
 ---> Cleaning up

---- Starting 1 new unit ----
 ---> Started unit 4d155e805f...

---- Adding routes to 1 new units ----
 ---> Added route to unit 4d155e805f

---- Removing routes from 1 old units ----
 ---> Removed route from unit d2811c0801

---- Removing 1 old unit ----
 ---> Removed old unit 1/1

OK

$ cat Procfile
web: mvn jetty:run

$ cat tsuru.yaml
hooks:
  build:
    - mvn package

$ tsuru app-info -a helloweb
Application: helloweb
Repository: git@192.168.50.4.nip.io:helloweb.git
Platform: java
Teams: admin
Address: helloweb.192.168.50.4.nip.io
Owner: admin@example.com
Team owner: admin
Deploys: 2
Pool: theonepool
Units: 1
+------------+---------+
| Unit       | State   |
+------------+---------+
| 313458bb9d | started |
+------------+---------+

App Plan:
+---------------+--------+------+-----------+--------+---------+
| Name          | Memory | Swap | Cpu Share | Router | Default |
+---------------+--------+------+-----------+--------+---------+
| autogenerated | 0 MB   | 0 MB | 100       |        | false   |
+---------------+--------+------+-----------+--------+---------+

$ git push git@192.168.50.4.nip.io:helloweb.git master
Counting objects: 25, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (19/19), done.
Writing objects: 100% (25/25), 2.59 KiB | 0 bytes/s, done.
Total 25 (delta 5), reused 0 (delta 0)
remote: tar: Removing leading `/' from member names
remote: [INFO] Scanning for projects...
remote: [INFO]
remote: [INFO] ------------------------------------------------------------------------
remote: [INFO] Building helloweb Maven Webapp 1.0-SNAPSHOT
remote: [INFO] ------------------------------------------------------------------------
remote: Downloading: http://repo.maven.apache.org/maven2/org/apache/maven/plugins/maven-resources-plugin/2.3/maven-resources-plugin-2.3.pom
remote: Downloaded: http://repo.maven.apache.org/maven2/org/apache/maven/plugins/maven-resources-plugin/2.3/maven-resources-plugin-2.3.pom (5 KB at 6.0 KB/sec)
remote: Downloading: http://repo.maven.apache.org/maven2/org/apache/maven/plugins/maven-plugins/12/maven-plugins-12.pom
remote: Downloaded: http://repo.maven.apache.org/maven2/org/apache/maven/plugins/maven-plugins/12/maven-plugins-12.pom (12 KB at 35.9 KB/sec)

...

remote: [INFO] Packaging webapp
remote: [INFO] Assembling webapp [helloweb] in [/home/application/current/target/helloweb]
remote: [INFO] Processing war project
remote: [INFO] Copying webapp resources [/home/application/current/src/main/webapp]
remote: [INFO] Webapp assembled in [27 msecs]
remote: [INFO] Building war: /home/application/current/target/helloweb.war
remote: [INFO] WEB-INF/web.xml already added, skipping
remote: [INFO] ------------------------------------------------------------------------
remote: [INFO] BUILD SUCCESS
remote: [INFO] ------------------------------------------------------------------------
remote: [INFO] Total time: 51.729s
remote: [INFO] Finished at: Tue Nov 11 17:04:05 UTC 2014
remote: [INFO] Final Memory: 8M/19M
remote: [INFO] ------------------------------------------------------------------------
remote:
remote: ---- Building application image ----
remote:  ---> Sending image to repository (2.96MB)
remote:  ---> Cleaning up
remote:
remote: ---- Starting 1 new unit ----
remote:  ---> Started unit e71d176232...
remote:
remote: ---- Adding routes to 1 new units ----
remote:  ---> Added route to unit e71d176232
remote:
remote: ---- Removing routes from 1 old units ----
remote:  ---> Removed route from unit d8a2d14948
remote:
remote: ---- Removing 1 old unit ----
remote:  ---> Removed old unit 1/1
remote:
remote: OK
To git@tsuru.mycompany.com:helloweb.git
 * [new branch]      master -> master

Switching between Java versions¶

In the Java platform provided by tsuru, users can use two version of Java: 7 and 8, both provided by Oracle. There’s an environment variable for defining the Java version you wanna use: JAVA_VERSION. The default behavior of the platform is to use Java 7, but you can change to Java 8 by running:

$ tsuru env-set -a helloweb JAVA_VERSION=8
---- Setting 1 new environment variables ----

---- Starting 1 new unit ----
 ---> Started unit d8a2d14948...

---- Adding routes to 1 new units ----
 ---> Added route to unit d8a2d14948

---- Removing routes from 1 old units ----
 ---> Removed route from unit 4d155e805f

---- Removing 1 old unit ----
 ---> Removed old unit 1/1

And... done! No need to run another deployment, your application is now running with Java 8.

Setting memory for application¶

In the Java platform provided by tsuru, users can use units with diferent plans and each plan may have containers with different amounts of memory. There’s an environment variable for defining the max amount of heap memory (in megabytes) that Java should use: JAVA_MAX_MEMORY ( it’s equal -Xmx). The default value for this environment variable is 128 (it can be different according to your basebuilder).

$ tsuru env-set -a helloweb JAVA_MAX_MEMORY=1024
---- Setting 1 new environment variables ----

---- Starting 1 new unit ----
 ---> Started unit o5p1k70289...

---- Adding routes to 1 new units ----
 ---> Added route to unit o5p1k70289

---- Removing routes from 1 old units ----
 ---> Removed route from unit d8a2d14948

---- Removing 1 old unit ----
 ---> Removed old unit 1/1

And... done! No need to run another deployment, your application is now running with more memory.

Going further¶

For more information, you can dig into tsuru docs, or read complete instructions of use for the tsuru command.

Overview¶

This document is a hands-on guide to deploying a simple PHP application in tsuru. The example application will be a very simple Wordpress project associated to a MySQL service. It’s applicable to any php over apache application.

Creating the app in tsuru¶

To create an app, you use the command app-create:

$ tsuru app-create <app-name> <app-platform>

For PHP, the app platform is, guess what, php! Let’s be over creative and develop a never-developed tutorial-app: a blog, and its name will also be very creative, let’s call it “blog”:

$ tsuru app-create blog php

To list all available platforms, use the command platform-list.

You can see all your applications using the command app-list:

$ tsuru app-list
+-------------+-------------------------+--------------------------+
| Application | Units State Summary     | Address                  |
+-------------+-------------------------+--------------------------+
| blog        | 0 of 0 units in-service | blog.192.168.50.4.nip.io |
+-------------+-------------------------+--------------------------+

Application code¶

This document will not focus on how to write a php blog, you can download the entire source direct from wordpress: http://wordpress.org/latest.zip. Here is all you need to do with your project:

# Download and unpack wordpress
$ wget http://wordpress.org/latest.zip
$ unzip latest.zip
# Preparing wordpress for tsuru
$ cd wordpress
# Notify tsuru about the necessary packages
$ echo php5-mysql > requirements.apt
# Preparing the application to receive the tsuru environment related to the mysql service
$ sed "s/'database_name_here'/getenv('MYSQL_DATABASE_NAME')/; \
            s/'username_here'/getenv('MYSQL_USER')/; \
            s/'localhost'/getenv('MYSQL_HOST')/; \
            s/'password_here'/getenv('MYSQL_PASSWORD')/" \
            wp-config-sample.php  > wp-config.php
# Creating a local Git repository
$ git init
$ git add .
$ git commit -m 'initial project version'

Git deployment¶

When you create a new app, tsuru will display the Git remote that you should use. You can always get it using the command app-info:

$ tsuru app-info --app blog
Application: blog
Repository: git@192.168.50.4.nip.io:blog.git
Platform: php
Teams: admin
Address: blog.192.168.50.4.nip.io
Owner: admin@example.com
Team owner: admin
Deploys: 0
Pool: theonepool

App Plan:
+---------------+--------+------+-----------+--------+---------+
| Name          | Memory | Swap | Cpu Share | Router | Default |
+---------------+--------+------+-----------+--------+---------+
| autogenerated | 0 MB   | 0 MB | 100       |        | false   |
+---------------+--------+------+-----------+--------+---------+

The Git remote will be used to deploy your application using Git. You can just push to tsuru remote and your project will be deployed:

$ git push git@192.168.50.4.nip.io:blog.git master
Counting objects: 1295, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (1271/1271), done.
Writing objects: 100% (1295/1295), 6.09 MiB | 5.65 MiB/s, done.
Total 1295 (delta 102), reused 0 (delta 0)
remote: text
remote: Deploying the PHP application...
remote: tar: Removing leading `/' from member names
#########################################
#  OMIT DEPENDENCIES STEPS (see below)  #
#########################################
remote:
remote: ---- Building application image ----
remote:  ---> Sending image to repository (51.40MB)
remote:  ---> Cleaning up
remote:
remote: ---- Starting 1 new unit ----
remote:  ---> Started unit 027c2a31a0...
remote:
remote: ---- Binding and checking 1 new units ----
remote:  ---> Bound and checked unit 027c2a31a0
remote:
remote: ---- Adding routes to 1 new units ----
remote:  ---> Added route to unit 027c2a31a0
remote:
remote: OK
To git@192.168.50.4.nip.io:blog.git
 * [new branch]      master -> master

If you get a “Permission denied (publickey).”, make sure you’re member of a team and have a public key added to tsuru. To add a key, use the command key-add:

$ tsuru key-add mykey ~/.ssh/id_dsa.pub

You can use git remote add to avoid typing the entire remote url every time you want to push:

$ git remote add tsuru git@192.168.50.4.nip.io:blog.git

Then you can run:

$ git push tsuru master
Everything up-to-date

And you will be also able to omit the --app flag from now on:

$ tsuru app-info
Application: blog
Repository: git@192.168.50.4.nip.io:blog.git
Platform: php
Teams: admin
Address: blog.192.168.50.4.nip.io
Owner: admin@example.com
Team owner: admin
Deploys: 1
Pool: theonepool
Units: 1
+------------+---------+
| Unit       | State   |
+------------+---------+
| 027c2a31a0 | started |
+------------+---------+

App Plan:
+---------------+--------+------+-----------+--------+---------+
| Name          | Memory | Swap | Cpu Share | Router | Default |
+---------------+--------+------+-----------+--------+---------+
| autogenerated | 0 MB   | 0 MB | 100       |        | false   |
+---------------+--------+------+-----------+--------+---------+

Listing dependencies¶

In the last section we omitted the dependencies step of deploy. In tsuru, an application can have two kinds of dependencies:

• Operating system dependencies, represented by packages in the package manager of the underlying operating system (e.g.: yum and apt-get);
• Platform dependencies, represented by packages in the package manager of the platform/language (e.g. in Python, pip).

All apt-get dependencies must be specified in a requirements.apt file, located in the root of your application, and pip dependencies must be located in a file called requirements.txt, also in the root of the application. Since we will use MySQL with PHP, we need to install the package depends on just one apt-get package: php5-mysql, so here is how requirements.apt looks like:

php5-mysql

You can see the complete output of installing these dependencies below:

% git push tsuru master
#####################################
#                OMIT               #
#####################################
Counting objects: 1155, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (1124/1124), done.
Writing objects: 100% (1155/1155), 4.01 MiB | 327 KiB/s, done.
Total 1155 (delta 65), reused 0 (delta 0)
remote: Cloning into '/home/application/current'...
remote: Reading package lists...
remote: Building dependency tree...
remote: Reading state information...
remote: The following extra packages will be installed:
remote:   libmysqlclient18 mysql-common
remote: The following NEW packages will be installed:
remote:   libmysqlclient18 mysql-common php5-mysql
remote: 0 upgraded, 3 newly installed, 0 to remove and 0 not upgraded.
remote: Need to get 1042 kB of archives.
remote: After this operation, 3928 kB of additional disk space will be used.
remote: Get:1 http://archive.ubuntu.com/ubuntu/ quantal/main mysql-common all 5.5.27-0ubuntu2 [13.7 kB]
remote: Get:2 http://archive.ubuntu.com/ubuntu/ quantal/main libmysqlclient18 amd64 5.5.27-0ubuntu2 [949 kB]
remote: Get:3 http://archive.ubuntu.com/ubuntu/ quantal/main php5-mysql amd64 5.4.6-1ubuntu1 [79.0 kB]
remote: Fetched 1042 kB in 1s (739 kB/s)
remote: Selecting previously unselected package mysql-common.
remote: (Reading database ... 23874 files and directories currently installed.)
remote: Unpacking mysql-common (from .../mysql-common_5.5.27-0ubuntu2_all.deb) ...
remote: Selecting previously unselected package libmysqlclient18:amd64.
remote: Unpacking libmysqlclient18:amd64 (from .../libmysqlclient18_5.5.27-0ubuntu2_amd64.deb) ...
remote: Selecting previously unselected package php5-mysql.
remote: Unpacking php5-mysql (from .../php5-mysql_5.4.6-1ubuntu1_amd64.deb) ...
remote: Processing triggers for libapache2-mod-php5 ...
remote:  * Reloading web server config
remote:    ...done.
remote: Setting up mysql-common (5.5.27-0ubuntu2) ...
remote: Setting up libmysqlclient18:amd64 (5.5.27-0ubuntu2) ...
remote: Setting up php5-mysql (5.4.6-1ubuntu1) ...
remote: Processing triggers for libc-bin ...
remote: ldconfig deferred processing now taking place
remote: Processing triggers for libapache2-mod-php5 ...
remote:  * Reloading web server config
remote:    ...done.
remote: sudo: unable to resolve host 8cf20f4da877
remote: sudo: unable to resolve host 8cf20f4da877
remote: debconf: unable to initialize frontend: Dialog
remote: debconf: (Dialog frontend will not work on a dumb terminal, an emacs shell buffer, or without a controlling terminal.)
remote: debconf: falling back to frontend: Readline
remote: debconf: unable to initialize frontend: Dialog
remote: debconf: (Dialog frontend will not work on a dumb terminal, an emacs shell buffer, or without a controlling terminal.)
remote: debconf: falling back to frontend: Readline
remote:
remote: Creating config file /etc/php5/mods-available/mysql.ini with new version
remote: debconf: unable to initialize frontend: Dialog
remote: debconf: (Dialog frontend will not work on a dumb terminal, an emacs shell buffer, or without a controlling terminal.)
remote: debconf: falling back to frontend: Readline
remote:
remote: Creating config file /etc/php5/mods-available/mysqli.ini with new version
remote: debconf: unable to initialize frontend: Dialog
remote: debconf: (Dialog frontend will not work on a dumb terminal, an emacs shell buffer, or without a controlling terminal.)
remote: debconf: falling back to frontend: Readline
remote:
remote: Creating config file /etc/php5/mods-available/pdo_mysql.ini with new version
remote:
remote:  ---> App will be restarted, please check its log for more details...
remote:
To git@192.168.50.4.nip.io:blog.git
 * [new branch]      master -> master

Running the application¶

As you can see, in the deploy output there is a step described as “App will be restarted”. In this step, tsuru will restart your app if it’s running, or start it if it’s not. Now that the app is deployed, you can access it from your browser, getting the IP or host listed in app-list and opening it. For example, in the list below:

$ tsuru app-list
+-------------+-------------------------+---------------------+
| Application | Units State Summary     | Address             |
+-------------+-------------------------+---------------------+
| blog        | 1 of 1 units in-service | blog.cloud.tsuru.io |
+-------------+-------------------------+---------------------+

Customizing the platform¶

The PHP platform supports customizations in the frontend and the interpreter, for more details, check the README of the platform.

Going further¶

For more information, you can dig into tsuru docs, or read complete instructions of use for the tsuru command.

Creating an Application¶

What do you need is create an application using buildpack platform:

$ tsuru app-create myapp buildpack

Deploying your Application¶

Use git push to deploy your application.

$ git push <REMOTE-URL> master

Included Buildpacks¶

A number of buildpacks come bundled by default:

• https://github.com/heroku/heroku-buildpack-ruby.git
• https://github.com/heroku/heroku-buildpack-nodejs.git
• https://github.com/heroku/heroku-buildpack-java.git
• https://github.com/heroku/heroku-buildpack-play.git
• https://github.com/heroku/heroku-buildpack-python.git
• https://github.com/heroku/heroku-buildpack-scala.git
• https://github.com/heroku/heroku-buildpack-clojure.git
• https://github.com/heroku/heroku-buildpack-gradle.git
• https://github.com/heroku/heroku-buildpack-grails.git
• https://github.com/CHH/heroku-buildpack-php.git
• https://github.com/kr/heroku-buildpack-go.git
• https://github.com/oortcloud/heroku-buildpack-meteorite.git
• https://github.com/miyagawa/heroku-buildpack-perl.git
• https://github.com/igrigorik/heroku-buildpack-dart.git
• https://github.com/rhy-jot/buildpack-nginx.git
• https://github.com/Kloadut/heroku-buildpack-static-apache.git
• https://github.com/bacongobbler/heroku-buildpack-jekyll.git
• https://github.com/ddollar/heroku-buildpack-multi.git

tsuru will cycle through the bin/detect script of each buildpack to match the code you are pushing.

Using a Custom Buildpack¶

To use a custom buildpack, set the BUILDPACK_URL environment variable.

$ tsuru env-set BUILDPACK_URL=https://github.com/dpiddy/heroku-buildpack-ruby-minimal

On your next git push, the custom buildpack will be used.

Creating your own Buildpack¶

You can follow this Heroku documentation to learn how to create your own Buildpack: https://devcenter.heroku.com/articles/buildpack-api.

Overview¶

Tsuru provide ways you to use external services, with that you can have a database, a storage and a lot of other services.

Using¶

The service workflow can be resumed to two steps:

1. Create a service instance
2. Bind the service instance to the app

To start you have to list all services provided by tsuru:

$ tsuru service-list
+----------------+-----------+
| Services       | Instances |
+----------------+-----------+
| elastic-search |           |
| mysql          |           |
+----------------+-----------+

The output from service-list above says that there are two available services: “elastic-search” and “mysql”, and no instances. To create our MySQL instance, we should run the command service-instance-add:

$ tsuru service-instance-add mysql db_instance
Service successfully added.

Now, if we run service-list again, we will see our new service instance in the list:

$ tsuru service-list
+----------------+---------------+
| Services       | Instances     |
+----------------+---------------+
| elastic-search |               |
| mysql          | db_instance   |
+----------------+---------------+

To bind the service instance to the application, we use the command service-instance-bind:

$ tsuru service-instance-bind mysql db_instance -a myapp
Instance blogsql is now bound to the app myapp.

The following environment variables are now available for use in your app:

- MYSQL_PORT
- MYSQL_PASSWORD
- MYSQL_USER
- MYSQL_HOST
- MYSQL_DATABASE_NAME

For more details, please check the documentation for the service, using service-doc command.

As you can see from bind output, we use environment variables to connect to the MySQL server. Next step is update your app to use these variables to connect in the database.

After update it and deploy the new version your app will be able to comunicate with service.

More tools¶

To see more information about a service you should use service-info <service_name>:

$ tsuru service-info mysql
Info for "mysql"

Instances
+-------------+---------+-------+
| Instances   | Plan    | Apps  |
+-------------+---------+-------+
| db_instance | default | myapp |
+-----------------------+-------+

Plans
+---------+------------+
| Name    | Description|
+---------+------------+
| medium  | 2G Memory  |
| default | 1G Memory  |
+---------+------------+

After create a new service instance, sometimes it takes a while to be done. To see the state of a service instance you should use service-instance-status <service_name> <service_instance>:

$ tsuru service-instance-status mysql db_instance
Service instance "db_instance" is pending

After service-instance-status command return up to instance, you are free to use it with your app.

Check your application logs¶

tsuru aggregates stdout and stderr from every application process making it easier to troubleshoot problems.

To know more how the tsuru log works see the log documentation.

Restart your application¶

Some application issues are solved by a simple restart. For example, your application may need to be restarted after a schema change to your database.

$ tsuru app-restart -a appname

Checking the status of application units¶

$ tsuru app-info -a appname

Open a shell to the application¶

You can also use tsuru app-shell to open a remote shell to one of the units of the application.

$ tsuru app-shell -a appname

You can also specify the unit ID to connect:

$ tsuru app-shell -a appname <container-id>

Watch your logs¶

On its default installation tsuru will have all logs available using the tsuru app-log command.

It’s possible that viewing logs using tsuru was disabled by an administrator. In this case running tsuru app-log will show instructions on how logs can be read.

For more informations about configuring the destination of logs and enabling/disabling tsuru app-log see Managing Application Logs.

$ tsuru app-log -a <appname>
2014-12-11 16:36:17 -0200 [tsuru][api]:  ---> Removed route from unit 1d913e0910
2014-12-11 16:36:17 -0200 [tsuru][api]: ---- Removing 1 old unit ----
2014-12-11 16:36:22 -0200 [app][11f863b2c14b]: Starting gunicorn 18.0
2014-12-11 16:36:22 -0200 [app][11f863b2c14b]: Listening at: http://0.0.0.0:8100 (51)
2014-12-11 16:36:22 -0200 [app][11f863b2c14b]: Using worker: sync
2014-12-11 16:36:22 -0200 [app][11f863b2c14b]: Booting worker with pid: 60
2014-12-11 16:36:28 -0200 [tsuru][api]:  ---> Removed old unit 1/1

$ tsuru app-log -a <appname> --lines 100

$ tsuru app-log -a <appname> --unit 11f863b2c14b
2014-12-11 16:36:22 -0200 [app][11f863b2c14b]: Starting gunicorn 18.0
2014-12-11 16:36:22 -0200 [app][11f863b2c14b]: Listening at: http://0.0.0.0:8100 (51)
2014-12-11 16:36:22 -0200 [app][11f863b2c14b]: Using worker: sync

$ tsuru app-log -a <appname> --source app
2014-12-11 16:36:22 -0200 [app][11f863b2c14b]: Starting gunicorn 18.0
2014-12-11 16:36:22 -0200 [app][11f863b2c14b]: Listening at: http://0.0.0.0:8100 (51)
2014-12-11 16:36:22 -0200 [app][11f863b2c14b]: Using worker: sync

$ tsuru app-log -a <appname> --source tsuru
2014-12-11 16:36:17 -0200 [tsuru][api]:  ---> Removed route from unit 1d913e0910
2014-12-11 16:36:17 -0200 [tsuru][api]: ---- Removing 1 old unit ----

$ tsuru app-log -a <appname> --follow

Syntax¶

Procfile is a plain text file called Procfile placed at the root of your application.

Each project should be represented by a name and a command, like below:

<name>: <command>

The name is a string which may contain alphanumerics and underscores and identifies one type of process.

command is a shell commandline which will be executed to spawn a process.

Environment variables¶

You can reference yours environment variables in the command:

web: ./manage.py runserver 0.0.0.0:$PORT

For more information about Procfile you can see the honcho documentation about Procfiles: http://honcho.rtfd.org/en/latest/using_procfiles.html.

Deployment hooks¶

tsuru provides some deployment hooks, like restart:before, restart:after and build. Deployment hooks allow developers to run commands before and after some commands.

Here is an example about how to declare this hooks in your tsuru.yaml file:

hooks:
  restart:
    before:
      - python manage.py generate_local_file
    after:
      - python manage.py clear_local_cache
  build:
    - python manage.py collectstatic --noinput
    - python manage.py compress

tsuru supports the following hooks:

• restart:before: this hook lists commands that will run before the unit is restarted. Commands listed in this hook will run once per unit. For instance, imagine there’s an app with two units and the tsuru.yaml file listed above. The command python manage.py generate_local_file would run two times, once per unit.
• restart:after: this hook is like before-each, but runs after restarting a unit.
• build: this hook lists commands that will be run during deploy, when the image is being generated.

Healthcheck¶

You can declare a health check in your tsuru.yaml file. This health check will be called during the deployment process and tsuru will make sure this health check is passing before continuing with the deployment process.

If tsuru fails to run the health check successfully it will abort the deployment before switching the router to point to the new units, so your application will never be unresponsive. You can configure the maximum time to wait for the application to respond with the docker:healthcheck:max-time config.

Here is how you can configure a health check in your yaml file:

healthcheck:
  path: /healthcheck
  method: GET
  status: 200
  match: .*OKAY.*
  allowed_failures: 0
  use_in_router: false

• healthcheck:path: Which path to call in your application. This path will be called for each unit. It is the only mandatory field, if it’s not set your health check will be ignored.
• healthcheck:method: The method used to make the http request. Defaults to GET.
• healthcheck:status: The expected response code for the request. Defaults to 200.
• healthcheck:match: A regular expression to be matched against the request body. If it’s not set the body won’t be read and only the status code will be checked. This regular expression uses Go syntax and runs with . matching \n (s flag).
• healthcheck:allowed_failures: The number of allowed failures before that the health check consider the application as unhealthy. Defaults to 0.
• healthcheck:use_in_router: Whether this health check path should also be registered in the router. Please, ensure that the check is consistent to prevent units being disabled by the router. Defaults to false.

Installing a plugin¶

Let’s install a plugin. There are two ways to install a plugin. The first way is to move your plugin to $HOME/.tsuru/plugins. The other way is to use the command tsuru plugin-install.

tsuru plugin-install will download the plugin file to $HOME/.tsuru/plugins. The syntax for this command is:

$ tsuru plugin-install <plugin-name> <plugin-url>

Listing installed plugins¶

To list all installed plugins, users can use the command tsuru plugin-list:

$ tsuru plugin-list
plugin1
plugin2

Executing a plugin¶

To execute a plugin just follow this pattern tsuru <plugin-name> <args>:

$ tsuru <plugin-name>
<plugin-output>

Removing a plugin¶

To remove a plugin just use the command tsuru plugin-remove passing the name of the plugin as argument:

$ tsuru plugin-remove <plugin-name>
Plugin "<plugin-name>" successfully removed!

Creating your own plugin¶

All you need to do is to create a new file that can be executed. You can use Shell Script, Python, Ruby, etc.

As an example, we’re going to show how to create a Hello world plugin, that just prints “hello world!” in the screen. Let’s use Shell Script in this plugin:

#!/bin/bash -e
echo "hello world!"

You can use the gist (https://gist.github.com) as host for your plugin, and run tsuru plugin-install to install it:

$ tsuru plugin-install hello https://gist.githubusercontent.com/fsouza/702a767f48b0ceaafebe/raw/9bcdf9c015fda5ca410ca5eaf254a806bddfcab3/hello.bash

Preparing Your Application¶

If you follow the 12 Factor app principles you shouldn’t have to change your application in order to deploy it on tsuru. Here is what an application need to go on a tsuru cloud:

1. Well defined requirements, both, on language level and operational system level
2. Configuration of external resources using environment variables
3. A Procfile to tell how your process should be run

Let’s go a little deeper through each of those topics.

python-dev
libmysqlclient-dev

import os

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.mysql",
        "NAME": os.environ.get("MYSQLAPI_DB_NAME"),
        "USER": os.environ.get("MYSQLAPI_DB_USER"),
        "PASSWORD": os.environ.get("MYSQLAPI_DB_PASSWORD"),
        "HOST": os.environ.get("MYSQLAPI_HOST"),
        "PORT": "",
    }
}

Authentication¶

tsuru will authenticate with the service API using HTTP basic authentication. The user can be username or name of the service, and the password is defined in the service manifest.

Content-types¶

tsuru uses application/x-www-form-urlencoded in requests and expect application/json in responses.

Here is an example of a request from tsuru, to the service API:

POST /resources HTTP/1.1
Host: myserviceapi.com
User-Agent: Go 1.1 package http
Content-Length: 38
Accept: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Type: application/x-www-form-urlencoded

name=myinstance&plan=small&team=myteam

Listing available plans¶

tsuru will list the available plans whenever the user issues the command service-info

$ tsuru service-info mysql

It will display all instances of the service that the user has access to, and also the list of plans, that tsuru gets from the service API by issuing a GET on /resources/plans. Example of request:

GET /resources/plans HTTP/1.1
Host: myserviceapi.com
User-Agent: Go 1.1 package http
Accept: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Type: application/x-www-form-urlencoded

The API should return the following HTTP response codes with the respective response body:

• 200: if the operation has succeeded. The response body should include the list of the plans, in JSON format. Each plan contains a “name” and a “description”. Example of response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[{"name":"small","description":"plan for small instances"},
 {"name":"medium","description":"plan for medium instances"},
 {"name":"huge","description":"plan for huge instances"}]

In case of failure, the service API should return the status 500, explaining what happened in the response body.

Creating a new instance¶

This process begins when a tsuru customer creates an instance of the service via command line tool:

$ tsuru service-instance-add mysql mysql_instance

tsuru calls the service API to create a new instance via POST on /resources (please notice that tsuru does not include a trailing slash) with the name, plan and the team that owns the instance. Example of request:

POST /resources HTTP/1.1
Host: myserviceapi.com
Content-Length: 56
User-Agent: Go 1.1 package http
Accept: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Type: application/x-www-form-urlencoded

name=mysql_instance&plan=small&team=myteam&user=username

The API should return the following HTTP response codes with the respective response body:

• 201: when the instance is successfully created. There’s no need to include any body, as tsuru doesn’t expect to get any content back in case of success.
• 500: in case of any failure in the operation. tsuru expects that the service API includes an explanation of the failure in the response body.

Binding an app to a service instance¶

This process begins when a tsuru customer binds an app to an instance of the service via command line tool:

$ tsuru service-instance-bind mysql mysql_instance --app my_app

Now, tsuru services has two bind endpoints: /resources/<service-instance-name>/bind and /resources/<service-instance-name>/bind-app. The first endpoint will be called every time an app adds an unit. This endpoint is a POST with app-host and unit-host, where app-host represents the host to which the app is accessible, and unit-host is the address of the unit. Example of request:

POST /resources/myinstance/bind HTTP/1.1
Host: myserviceapi.com
User-Agent: Go 1.1 package http
Content-Length: 48
Accept: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Type: application/x-www-form-urlencoded

app-host=myapp.cloud.tsuru.io&unit-host=10.4.3.2

The second endpoint /resources/<service-instance-name>/bind-app will be called once when an app is bound to a service. This endpoint is a POST with app-host, where app-host represents the host to which the app is accessible. Example of request:

POST /resources/myinstance/bind-app HTTP/1.1
Host: myserviceapi.com
User-Agent: Go 1.1 package http
Content-Length: 48
Accept: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Type: application/x-www-form-urlencoded

app-host=myapp.cloud.tsuru.io

The service API should return the following HTTP response code with the respective response body:

• 201: if the app has been successfully bound to the instance. The response body must be a JSON containing the environment variables from this instance that should be exported in the app in order to connect to the instance. If the service does not export any environment variable, it can return null or {} in the response body. Example of response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=UTF-8

{"MYSQL_HOST":"10.10.10.10","MYSQL_PORT":3306,
 "MYSQL_USER":"ROOT","MYSQL_PASSWORD":"s3cr3t",
 "MYSQL_DATABASE_NAME":"myapp"}

Status codes for errors in the process:

• 404: if the service instance does not exist. There’s no need to include anything in the response body.
• 412: if the service instance is still being provisioned, and not ready for binding yet. The service API may include an explanation of the failure in the response body.
• 500: in case of any failure in the operation. tsuru expects that the service API includes an explanation of the failure in the response body.

Unbind an app from a service instance¶

This process begins when a tsuru customer unbinds an app from an instance of the service via command line:

$ tsuru service-instance-unbind mysql mysql_instance --app my_app

Now, tsuru services has two unbind endpoints: /resources/<service-instance-name>/bind and /resources/<service-instance-name>/bind-app. The first endpoint will be called every time an app removes an unit. This endpoint is a DELETE with app-host and unit-host. Example of request:

DELETE /resources/myinstance/bind HTTP/1.1
Host: myserviceapi.com
User-Agent: Go 1.1 package http
Accept: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Type: application/x-www-form-urlencoded

app-host=myapp.cloud.tsuru.io&unit-host=10.4.3.2

The second endpoint /resources/<service-instance-name>/bind-app will be called once when the binding between a service and an application is removed. This endpoint is a DELETE with app-host. Example of request:

DELETE /resources/myinstance/bind-app HTTP/1.1
Host: myserviceapi.com
User-Agent: Go 1.1 package http
Accept: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Type: application/x-www-form-urlencoded

app-host=myapp.cloud.tsuru.io

The API should return the following HTTP response code with the respective response body:

• 200: if the operation has succeed and the app is not bound to the service instance anymore. There’s no need to include anything in the response body.
• 404: if the service instance does not exist. There’s no need to include anything in the response body.
• 500: in case of any failure in the operation. tsuru expects that the service API includes an explanation of the failure in the response body.

Removing an instance¶

This process begins when a tsuru customer removes an instance of the service via command line:

$ tsuru service-instance-remove mysql mysql_instance -y

tsuru calls the service API to remove the instancevia DELETE on /resources/<service-name> (please notice that tsuru does not include a trailing slash). Example of request:

DELETE /resources/myinstance HTTP/1.1
Host: myserviceapi.com
User-Agent: Go 1.1 package http
Accept: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Type: application/x-www-form-urlencoded

The API should return the following HTTP response codes with the respective response body:

• 200: if the service instance has been successfully removed. There’s no need to include anything in the response body.
• 404: if the service instance does not exist. There’s no need to include anything in the response body.
• 500: in case of any failure in the operation. tsuru expects that the service API includes an explanation of the failure in the response body.

Checking the status of an instance¶

This process begins when a tsuru customer wants to check the status of an instance via command line:

$ tsuru service-instance-status mysql mysql_instance

tsuru calls the service API to check the status of the instance via GET on /resources/mysql_instance/status (please notice that tsuru does not include a trailing slash). Example of request:

GET /resources/myinstance/status HTTP/1.1
Host: myserviceapi.com
User-Agent: Go 1.1 package http
Accept: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Type: application/x-www-form-urlencoded

The API should return the following HTTP response code, with the respective response body:

• 202: the instance is still being provisioned (pending). There’s no need to include anything in the response body.
• 204: the instance is running and ready for connections (running).
• 500: the instance is not running, nor ready for connections. tsuru expects an explanation of what happened in the response body.

Additional info about an instance¶

When the user run tsuru service-info <service> or tsuru service-instance-info, tsuru will get informations from all instances. This is an optional endpoint in the service API. Some services does not provide any extra information for instances. Example of request:

GET /resources/myinstance HTTP/1.1
Host: myserviceapi.com
User-Agent: Go 1.1 package http
Accept: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Type: application/x-www-form-urlencoded

The API should return the following HTTP response codes:

• 404: when the API doesn’t have extra info about the service instance. There’s no need to include anything in the response body.
• 200: when there’s extra information of the service instance. The response body must be a JSON containing a list of items. Each item is a JSON object combosed by a label and a value. Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[{"label":"my label","value":"my value"},
 {"label":"myLabel2.0","value":"my value 2.0"}]

Overview¶

This document is a hands-on guide to turning your existing cloud service into a tsuru service.

In order to create a service you need to implement a provisioning API for your service, which tsuru will call using HTTP protocol when a customer creates a new instance or binds a service instance with an app.

You will also need to create a YAML document that will serve as the service manifest. We provide a command-line tool to help you to create this manifest and manage your service.

Creating your service API¶

To create your service API, you can use any programming language or framework. In this tutorial we will use Flask.

Authentication¶

tsuru uses basic authentication for authenticating the services, for more details, check the service API workflow.

Using Flask, you can manage basic authentication using a decorator described in this Flask snippet: http://flask.pocoo.org/snippets/8/.

$ python --version
Python 2.7.2

$ pip
Usage: pip COMMAND [OPTIONS]

pip: error: You must give a command (use "pip help" to see a list of commands)

$ pip install flask

from flask import Flask
app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello World!"

if __name__ == "__main__":
    app.run()

$ python api.py
 * Running on http://127.0.0.1:5000/

import json


@app.route("/resources/plans", methods=["GET"])
def plans():
    plans = [{"name": "small", "description": "small instance"},
             {"name": "medium", "description": "medium instance"},
             {"name": "big", "description": "big instance"},
             {"name": "giant", "description": "giant instance"}]
    return json.dumps(plans)

from flask import request


@app.route("/resources", methods=["POST"])
def add_instance():
    name = request.form.get("name")
    plan = request.form.get("plan")
    team = request.form.get("team")
    # use the given parameters to create the instance
    return "", 201

import json

from flask import request


@app.route("/resources/<name>/bind-app", methods=["POST"])
def bind_app(name):
    app_host = request.form.get("app-host")
    # use name and app_host to bind the service instance and the #
    application
    envs = {"SOMEVAR": "somevalue"}
    return json.dumps(envs), 201

@app.route("/resources/<name>/bind-app", methods=["DELETE"])
def unbind_app(name):
    app_host = request.form.get("app-host")
    # use name and app-host to remove the bind
    return "", 200

@app.route("/resources/<name>/bind", methods=["POST", "DELETE"])
def access_control(name):
    app_host = request.form.get("app-host")
    unit_host = request.form.get("unit-host")
    # use unit-host and app-host, according to the access control tool, and
    # the request method.
    return "", 201

@app.route("/resources/<name>", methods=["DELETE"])
def remove_instance(name):
    # remove the instance named "name"
    return "", 200

@app.route("/resources/<name>/status", methods=["GET"])
def status(name):
    # check the status of the instance named "name"
    return "", 204

import json

from flask import Flask, request

app = Flask(__name__)


@app.route("/resources/plans", methods=["GET"])
def plans():
    plans = [{"name": "small", "description": "small instance"},
             {"name": "medium", "description": "medium instance"},
             {"name": "big", "description": "big instance"},
             {"name": "giant", "description": "giant instance"}]
    return json.dumps(plans)


@app.route("/resources", methods=["POST"])
def add_instance():
    name = request.form.get("name")
    plan = request.form.get("plan")
    team = request.form.get("team")
    # use the given parameters to create the instance
    return "", 201


@app.route("/resources/<name>/bind-app", methods=["POST"])
def bind_app(name):
    app_host = request.form.get("app-host")
    # use name and app_host to bind the service instance and the #
    application
    envs = {"SOMEVAR": "somevalue"}
    return json.dumps(envs), 201


@app.route("/resources/<name>/bind-app", methods=["DELETE"])
def unbind_app(name):
    app_host = request.form.get("app-host")
    # use name and app-host to remove the bind
    return "", 200


@app.route("/resources/<name>", methods=["DELETE"])
def remove_instance(name):
    # remove the instance named "name"
    return "", 200


@app.route("/resources/<name>/bind", methods=["POST", "DELETE"])
def access_control(name):
    app_host = request.form.get("app-host")
    unit_host = request.form.get("unit-host")
    # use unit-host and app-host, according to the access control tool, and
    # the request method.
    return "", 201


@app.route("/resources/<name>/status", methods=["GET"])
def status(name):
    # check the status of the instance named "name"
    return "", 204

if __name__ == "__main__":
    app.run()

Creating a service manifest¶

Using crane you can create a manifest template:

$ crane template

This will create a manifest.yaml in your current path with this content:

id: servicename
password: abc123
endpoint:
    production: production-endpoint.com

The manifest.yaml is used by crane to defined the ID, the password and the production endpoint of your service.

Change these information in the created manifest, and the submit your service:

id: servicename
username: username_to_auth
password: 1CWpoX2Zr46Jhc7u
endpoint:
  production: production-endpoint.com
    test: test-endpoint.com:8080

submit your service: Submiting your service API

Submiting your service API¶

To submit your service, you can run:

$ crane create manifest.yaml

For more details, check the service API workflow and the crane usage guide.

Installing¶

You will need a Elasticsearch and a Logstash installed.

tsuru send data to Logstash using udp protocol and the message is formatted in json that requires a custom Logstash configuration:

input {
    udp {
        port => 1984
    }
}

filter {
    json {
        source => "message"
    }

    if "_jsonparsefailure" in [tags] {
        mutate {
            add_field => {
                client => "error"
                metric => "metric_error"
            }
        }
    }
}

output {
    elasticsearch {
        hosts => ["http://ELASTICSEARCHHOST:ELASTICSEARCHPORT"]
        index => ".measure-%{client}-%{+YYYY.MM.dd}"
        document_type => "%{metric}"
    }
}

Configuring¶

You should use tsuru-admin node-container-update big-sibling –env NAME=VALUE to define the config values.

The available configs are:

METRICS_INTERVAL is the interval in seconds between metrics collecting and reporting from bs to the metric backend. The default value is 60 seconds.

METRICS_BACKEND is the metric backend. Only ‘logstash’ is supported right now.

Logstash specific configs:

METRICS_LOGSTASH_CLIENT is the client name used to identify who is sending the metric. The default value is tsuru.

METRICS_LOGSTASH_PORT is the Logstash port. The default value is 1984.

METRICS_LOGSTASH_HOST is the Logstash host. The default value is localhost.

Metrics graph on tsuru-dashboard¶

tsuru-dashboard can be used to show a graphic for each metric by application.

To enable it define the METRICS_ELASTICSEARCH_HOST using tsuru-admin node-container-update big-sibling –env.

Count based scaling¶

It’s chosen if docker:auto-scale:max-container-count is set to a value > 0 in your tsuru configuration.

Memory based scaling¶

It’s chosen if docker:auto-scale:max-container-count is not set and your scheduler is configured to use node’s memory information, by setting docker:scheduler:total-memory-metadata and docker:scheduler:max-used-memory.

Rebalancing nodes¶

Rebalancing containers will be triggered when a new node is added or if rebalancing would decrease the difference of containers in nodes by a number greater than 2, regardless the scaling algorithm.

Also, rebalancing will not run if docker:auto-scale:prevent-rebalance is set to true.

Auto scale events¶

Each time tsuru tries to run an auto scale action (add, remove, or rebalance). It will create an auto scale event. This event will record the result of the auto scale action and possible errors that occurred during its execution.

You can list auto scale events with tsuru-admin docker-autoscale-list

Running auto scale once¶

Even if you have docker:auto-scale:enabled set to false, you can make tsuru trigger the execution of the auto scale algorithm by running tsuru-admin docker- autoscale-run.

Notation¶

tsuru uses a colon to represent nesting in YAML. So, whenever this document says something like key1:key2, it refers to the value of the key2 that is nested in the block that is the value of key1. For example, database:url means:

database:
  url: <value>

tsuru configuration¶

This section describes tsuru’s core configuration. Other sections will include configuration of optional components, and finally, a full sample file.

<body>
    {{if getConfig "use-tls"}}
    <p>we're safe</p>
    {{else}}
    <p>we're not safe</p>
    {{end}}
</body>

docker:
  ...
  security-opts:
    - apparmor:PROFILE

IaaS configuration¶

tsuru uses IaaS configuration to automatically create new docker nodes and adding them to your cluster when using docker-node-add command. See adding nodes for more details about how to use this command.

iaas:
    custom:
        region1_cloudstack:
            provider: cloudstack
            url: http://region1.url/
            secret-key: mysecretkey
    cloudstack:
        api-key: myapikey

Sample file¶

Here is a complete example:

listen: "0.0.0.0:8080"
debug: true
host: http://<machine-public-addr>:8080 # This port must be the same as in the "listen" conf
auth:
    user-registration: true
    scheme: native
database:
    url: <your-mongodb-server>:27017
    name: tsurudb
pubsub:
    redis-host: <your-redis-server>
    redis-port: 6379
queue:
    mongo-url: <your-mongodb-server>:27017
    mongo-database: queuedb
git:
    api-server: http://<your-gandalf-server>:8000
provisioner: docker
docker:
    router: hipache
    collection: docker_containers
    repository-namespace: tsuru
    deploy-cmd: /var/lib/tsuru/deploy
    cluster:
        storage: mongodb
        mongo-url: <your-mongodb-server>:27017
        mongo-database: cluster
    run-cmd:
        bin: /var/lib/tsuru/start
        port: "8888"
routers:
    hipache:
        type: hipache
        domain: <your-hipache-server-ip>.xip.io
        redis-server: <your-redis-server-with-port>

set envs¶

• path: /apps/{app}/env
• produce: application/x-json-stream
• consume: application/x-www-form-urlencoded
• method: POST
• 200: Envs updated
• 400: Invalid data
• 404: App not found
• 401: Unauthorized

app log¶

• path: /apps/{app}/log
• consume: application/x-www-form-urlencoded
• method: POST
• 200: Ok
• 400: Invalid data
• 404: App not found
• 401: Unauthorized

app unlock¶

• path: /apps/{app}/lock
• produce: application/json
• method: DELETE
• 200: Ok
• 401: Unauthorized
• 404: App not found

app swap¶

• path: /swap
• consume: application/x-www-form-urlencoded
• method: POST
• 400: Invalid data
• 401: Unauthorized
• 404: App not found
• 200: Ok
• 409: App locked
• 412: Number of units or platform don’t match

app start¶

• path: /apps/{app}/start
• produce: application/x-json-stream
• consume: application/x-www-form-urlencoded
• method: POST
• 200: Ok
• 401: Unauthorized
• 404: App not found

revoke access to app¶

• path: /apps/{app}/teams/{team}
• method: DELETE
• 200: Access revoked
• 401: Unauthorized
• 403: Forbidden
• 404: App or team not found

app restart¶

• path: /apps/{app}/restart
• produce: application/x-json-stream
• consume: application/x-www-form-urlencoded
• method: POST
• 200: Ok
• 401: Unauthorized
• 404: App not found

register unit¶

• path: /apps/{app}/units/register
• produce: application/json
• consume: application/x-www-form-urlencoded
• method: POST
• 200: Ok
• 401: Unauthorized
• 404: App not found

metric envs¶

• path: /apps/{app}/metric/envs
• produce: application/json
• method: GET
• 200: Ok
• 401: Unauthorized
• 404: App not found

remove app¶

• path: /apps/{name}
• produce: application/x-json-stream
• method: DELETE
• 200: App removed
• 401: Unauthorized
• 404: Not found

grant access to app¶

• path: /apps/{app}/teams/{team}
• method: PUT
• 200: Access granted
• 401: Unauthorized
• 404: App or team not found
• 409: Grant already exists

app log¶

• path: /apps/{app}/log
• produce: application/x-json-stream
• method: GET
• 200: Ok
• 400: Invalid data
• 404: App not found
• 401: Unauthorized

bind service instance¶

• path: /services/{service}/instances/{instance}/{app}
• produce: application/x-json-stream
• consume: application/x-www-form-urlencoded
• method: PUT
• 200: Ok
• 400: Invalid data
• 404: App not found
• 401: Unauthorized

unset envs¶

• path: /apps/{app}/env
• produce: application/x-json-stream
• method: DELETE
• 200: Envs removed
• 400: Invalid data
• 404: App not found
• 401: Unauthorized

set cname¶

• path: /apps/{app}/cname
• consume: application/x-www-form-urlencoded
• method: POST
• 200: Ok
• 400: Invalid data
• 404: App not found
• 401: Unauthorized

app stop¶

• path: /apps/{app}/stop
• produce: application/x-json-stream
• consume: application/x-www-form-urlencoded
• method: POST
• 200: Ok
• 401: Unauthorized
• 404: App not found

rebuild routes¶

• path: /apps/{app}/routes
• produce: application/json
• method: POST
• 200: Ok
• 401: Unauthorized
• 404: App not found

app update¶

• path: /apps/{name}
• produce: application/x-json-stream
• consume: application/x-www-form-urlencoded
• method: PUT
• 200: App updated
• 401: Unauthorized
• 404: Not found

add units¶

• path: /apps/{name}/units
• produce: application/x-json-stream
• consume: application/x-www-form-urlencoded
• method: PUT
• 200: Units added
• 400: Invalid data
• 404: App not found
• 401: Unauthorized

set node status¶

• path: /node/status
• produce: application/json
• consume: application/x-www-form-urlencoded
• method: POST
• 200: Ok
• 400: Invalid data
• 404: App or unit not found
• 401: Unauthorized

get envs¶

• path: /apps/{app}/env
• produce: application/x-json-stream
• method: GET
• 200: OK
• 401: Unauthorized
• 404: App not found

app info¶

• path: /apps/{name}
• produce: application/json
• method: GET
• 200: OK
• 401: Unauthorized
• 404: Not found

app create¶

• path: /apps
• produce: application/json
• consume: application/x-www-form-urlencoded
• method: POST
• 400: Invalid data
• 201: App created
• 403: Quota exceeded
• 401: Unauthorized
• 409: App already exists

app list¶

• path: /apps
• produce: application/json
• method: GET
• 200: List apps
• 401: Unauthorized
• 204: No content

unbind service instance¶

• path: /services/{service}/instances/{instance}/{app}
• produce: application/x-json-stream
• method: DELETE
• 200: Ok
• 400: Invalid data
• 404: App not found
• 401: Unauthorized

set unit status¶

• path: /apps/{app}/units/{unit}
• consume: application/x-www-form-urlencoded
• method: POST
• 200: Ok
• 400: Invalid data
• 404: App or unit not found
• 401: Unauthorized

run commands¶

• path: /apps/{app}/run
• produce: application/x-json-stream
• consume: application/x-www-form-urlencoded
• method: POST
• 200: Ok
• 401: Unauthorized
• 404: App not found

app sleep¶

• path: /apps/{app}/sleep
• produce: application/x-json-stream
• consume: application/x-www-form-urlencoded
• method: POST
• 200: Ok
• 400: Invalid data
• 404: App not found
• 401: Unauthorized

remove units¶

• path: /apps/{name}/units
• produce: application/x-json-stream
• method: DELETE
• 200: Units removed
• 400: Invalid data
• 404: App not found
• 401: Unauthorized

unset cname¶

• path: /apps/{app}/cname
• method: DELETE
• 200: Ok
• 400: Invalid data
• 404: App not found
• 401: Unauthorized

user create¶

• path: /users
• consume: application/x-www-form-urlencoded
• method: POST
• 400: Invalid data
• 201: User created
• 403: Forbidden
• 401: Unauthorized
• 409: User already exists

change password¶

• path: /users/password
• consume: application/x-www-form-urlencoded
• method: PUT
• 200: Ok
• 400: Invalid data
• 403: Forbidden
• 404: Not found
• 401: Unauthorized

remove team¶

• path: /teams/{name}
• method: DELETE
• 200: Team removed
• 401: Unauthorized
• 403: Forbidden
• 404: Not found

user list¶

• path: /users
• produce: application/json
• method: GET
• 200: OK
• 401: Unauthorized

user info¶

• path: /users/info
• produce: application/json
• method: GET
• 200: OK
• 401: Unauthorized

add key¶

• path: /users/keys
• consume: application/x-www-form-urlencoded
• method: POST
• 200: Ok
• 400: Invalid data
• 401: Unauthorized
• 409: Key already exists

remove key¶

• path: /users/keys/{key}
• method: DELETE
• 200: Ok
• 400: Invalid data
• 404: Not found
• 401: Unauthorized

remove user¶

• path: /users
• method: DELETE
• 200: User removed
• 401: Unauthorized
• 404: Not found

logout¶

• path: /users/tokens
• method: DELETE
• 200: Ok

team list¶

• path: /teams
• produce: application/json
• method: GET
• 200: List teams
• 401: Unauthorized
• 204: No content

list keys¶

• path: /users/keys
• produce: application/json
• method: GET
• 200: OK
• 400: Invalid data
• 401: Unauthorized

regenerate token¶

• path: /users/api-key
• produce: application/json
• method: POST
• 200: OK
• 401: Unauthorized
• 404: User not found

show token¶

• path: /users/api-key
• produce: application/json
• method: GET
• 200: OK
• 401: Unauthorized
• 404: User not found

login¶

• path: /auth/login
• produce: application/json
• consume: application/x-www-form-urlencoded
• method: POST
• 200: Ok
• 400: Invalid data
• 403: Forbidden
• 404: Not found
• 401: Unauthorized

reset password¶

• path: /users/{email}/password
• method: POST
• 200: Ok
• 400: Invalid data
• 403: Forbidden
• 404: Not found
• 401: Unauthorized

team create¶

• path: /teams
• consume: application/x-www-form-urlencoded
• method: POST
• 400: Invalid data
• 201: Team created
• 401: Unauthorized
• 409: Team already exists

get auth scheme¶

• path: /auth/scheme
• produce: application/json
• method: GET
• 200: OK

dump goroutines¶

• path: /debug/goroutines
• method: GET
• 200: Ok

deploy list¶

• path: /deploys
• produce: application/json
• method: GET
• 200: OK
• 204: No content

deploy info¶

• path: /deploys/{deploy}
• produce: application/json
• method: GET
• 200: OK
• 401: Unauthorized
• 404: Not found

app deploy¶

• path: /apps/{appname}/deploy
• consume: application/x-www-form-urlencoded
• method: POST
• 200: OK
• 400: Invalid data
• 403: Forbidden
• 404: Not found

deploy diff¶

• path: /apps/{appname}/diff
• consume: application/x-www-form-urlencoded
• method: POST
• 200: OK
• 400: Invalid data
• 403: Forbidden
• 404: Not found

rollback¶

• path: /apps/{appname}/deploy/rollback
• produce: application/x-json-stream
• consume: application/x-www-form-urlencoded
• method: POST
• 200: OK
• 400: Invalid data
• 403: Forbidden
• 404: Not found

healthcheck¶

• path: /healthcheck
• method: GET
• 200: OK
• 500: Internal server error

template destroy¶

• path: /iaas/templates/{template_name}
• method: DELETE
• 200: OK
• 401: Unauthorized
• 404: Not found

template update¶

• path: /iaas/templates/{template_name}
• consume: application/x-www-form-urlencoded
• method: PUT
• 200: OK
• 400: Invalid data
• 404: Not found
• 401: Unauthorized

machine list¶

• path: /iaas/machines
• produce: application/json
• method: GET
• 200: OK
• 401: Unauthorized

machine destroy¶

• path: /iaas/machines/{machine_id}
• method: DELETE
• 200: OK
• 400: Invalid data
• 404: Not found
• 401: Unauthorized

machine template list¶

• path: /iaas/templates
• produce: application/json
• method: GET
• 200: OK
• 401: Unauthorized

template create¶

• path: /iaas/templates
• consume: application/x-www-form-urlencoded
• method: POST
• 400: Invalid data
• 201: Template created
• 401: Unauthorized

index¶

• path: /
• method: GET
• 200: OK

api info¶

• path: /info
• produce: application/json
• method: GET
• 200: OK

dissociate role from user¶

• path: /roles/{name}/user/{email}
• method: DELETE
• 200: Ok
• 400: Invalid data
• 404: Role not found
• 401: Unauthorized

list permissions¶

• path: /permissions
• produce: application/json
• method: GET
• 200: Ok
• 401: Unauthorized

remove default role¶

• path: /role/default
• method: DELETE
• 200: Ok
• 400: Invalid data
• 401: Unauthorized

list default roles¶

• path: /role/default
• produce: application/json
• method: GET
• 200: Ok
• 401: Unauthorized

role create¶

• path: /roles
• consume: application/x-www-form-urlencoded
• method: POST
• 400: Invalid data
• 201: Role created
• 401: Unauthorized
• 409: Role already exists

remove role¶

• path: /roles/{name}
• method: DELETE
• 200: Role removed
• 401: Unauthorized
• 404: Role not found

role list¶

• path: /roles
• produce: application/json
• method: GET
• 200: OK
• 401: Unauthorized

add permissions¶

• path: /roles/{name}/permissions
• consume: application/x-www-form-urlencoded
• method: POST
• 200: Ok
• 400: Invalid data
• 401: Unauthorized
• 409: Permission not allowed

assign role to user¶

• path: /roles/{name}/user
• consume: application/x-www-form-urlencoded
• method: POST
• 200: Ok
• 400: Invalid data
• 404: Role not found
• 401: Unauthorized

role info¶

• path: /roles/{name}
• produce: application/json
• method: GET
• 200: OK
• 401: Unauthorized
• 404: Role not found

add default role¶

• path: /role/default
• method: POST
• 200: Ok
• 400: Invalid data
• 401: Unauthorized

remove permission¶

• path: /roles/{name}/permissions/{permission}
• method: DELETE
• 200: Permission removed
• 401: Unauthorized
• 404: Not found

plan create¶

• path: /plans
• consume: application/x-www-form-urlencoded
• method: POST
• 400: Invalid data
• 201: Plan created
• 401: Unauthorized
• 409: Plan already exists

plan list¶

• path: /plans
• produce: application/json
• method: GET
• 200: OK
• 204: No content

remove plan¶

• path: /plans/{name}
• method: DELETE
• 200: Plan removed
• 401: Unauthorized
• 404: Plan not found

router list¶

• path: /plans/routers
• produce: application/json
• method: GET
• 200: OK
• 204: No content

add platform¶

• path: /platforms
• produce: application/x-json-stream
• consume: multipart/form-data
• method: POST
• 200: Platform created
• 400: Invalid data
• 401: Unauthorized

update platform¶

• path: /platforms/{name}
• produce: application/x-json-stream
• method: PUT
• 200: Platform updated
• 401: Unauthorized
• 404: Not found

remove platform¶

• path: /platforms/{name}
• method: DELETE
• 200: Platform removed
• 401: Unauthorized
• 404: Not found

platform list¶

• path: /platforms
• produce: application/json
• method: GET
• 200: List platforms
• 401: Unauthorized
• 204: No content

pool list¶

• path: /pools
• produce: application/json
• method: GET
• 200: OK
• 401: Unauthorized
• 404: User not found
• 204: No content

pool create¶

• path: /pools
• consume: application/x-www-form-urlencoded
• method: POST
• 400: Invalid data
• 201: Pool created
• 401: Unauthorized
• 409: Pool already exists

remove pool¶

• path: /pools/{name}
• method: DELETE
• 200: Pool removed
• 401: Unauthorized
• 404: Pool not found

add team too pool¶

• path: /pools/{name}/team
• consume: application/x-www-form-urlencoded
• method: POST
• 200: Pool updated
• 401: Unauthorized
• 400: Invalid data
• 404: Pool not found

remove team from pool¶

• path: /pools/{name}/team
• method: DELETE
• 200: Pool updated
• 401: Unauthorized
• 400: Invalid data
• 404: Pool not found

pool update¶

• path: /pools/{name}
• consume: application/x-www-form-urlencoded
• method: PUT
• 200: Pool updated
• 401: Unauthorized
• 404: Pool not found
• 409: Default pool already defined