Building and sharing tsuru app images

Since version 1.5.0, tsuru supports a new command that allows building app images and using them with different apps.

A typical app deploy with tsuru

When you deploy an app with tsuru app-deploy command, tsuru follows these steps:

1. tsuru client generates a .tar.gz file with all the files passed in the command line arguments
2. tsuru client sends the .tar.gz file on a POST request to tsuru API
3. tsuru API builds a Docker image with the app contents (using as base either the platform image or the previous app image)
4. tsuru API pushes the image to its image registry, tagged with an incremental version number and a builder suffix (something like registry.example.com/tsuru/app-myapp:v8-builder)
5. tsuru runs a container from this image, injects the environment variables defined for the app and runs the app deployment hooks
6. tsuru builds a new image from this container and also pushes it, labeled with the same version number but without the suffix (registry.example.com/tsuru/app-myapp:v8)
7. tsuru starts new units from this image

Deploys with git push are very similar, except for steps 1 and 2.

The problem with this approach is when you have many different tsuru apps for each environment — typically dev, qa, staging and production. Devs usually create apps like myapp-dev, myapp-qa, myapp-staging and myapp-prod to represent this. In a common development pipeline, devs deploy their code to the dev app; if everything works, they deploy this same code to qa, then staging and finally to production.

By default, when you do this, tsuru will create different images for each environment — their contents may be exactly equal, but the image names will be different — registry.example.com/tsuru/app-myapp-dev:v1, registry.example.com/tsuru/app-myapp-qa:v1, etc. If you could share an image among these apps — at least the builder images, without the environment variables, which may be specific per env — , the deploys would be faster (it wouldn't need to repeat steps 1 to 4 above, only steps 5 to 7), besides saving storage in the image registry (only one image would be pushed). And if you test the same image in every environment, you have more confidence it will work on the other environments.

The new tsuru app-build command allows sharing an image among different apps. You can also use this same image to run your app locally. Here's an example:

tsuru app-build -t mytag -a myapp <files>

This command will do the steps 1 to 4 from above, and display the address of the new image — something like registry.example.com/tsuru/app-myapp:mytag. Now you can deploy it to other apps using tsuru app-deploy -a otherapp -i registry.example.com/tsuru/app-myapp:mytag, or run in your local machine with Docker: docker run registry.example.com/tsuru/app-myapp:mytag.

This screencast shows tsuru app-build command in action:

app build in action

The app-build command is available since tsuru 1.5.0. To check other features of this version, take a look at the release notes.