Tools for building, testing, deploying Docker containers
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
bin fix smoke tests May 11, 2018
cli Merge branch 'master' into change-flavor-error Oct 22, 2018
cmd/sous-bootstrap Adjusting bootstrap docs to have less whitespace Aug 6, 2018
config cli+config: artifact get add add DFF Jul 17, 2018
database database: local dbchangelog-3.5.xsd Jul 27, 2018
dev_support testing with TC Apr 17, 2018
doc add more detail on SOUS_VERSION_SCHEME config Aug 10, 2018
dto Broken, right direction Apr 3, 2018
examples Updating the test Sous server Feb 10, 2017
ext refactor stderr grab to different function Oct 11, 2018
graph graph: +TestGetAddArtifact... Oct 19, 2018
integration qa env: upgrade Singularity to 0.20.1 Jun 21, 2018
lib Skip test added TODO Aug 15, 2018
notes Added a /defs endpoint Oct 6, 2016
scripts Switching DB to postgres Apr 26, 2018
server server: try listening again if fails Jul 25, 2018
test mark as integration Aug 16, 2018
util testmatrix: record test start earlier Aug 7, 2018
vendor merge config and vendoring Aug 8, 2018
.gitignore initial checking, WIP, not working, but general framework Aug 7, 2018
.travis.yml .travis.yml: run danger only once Oct 17, 2018 Merge branch 'master' into change-flavor-error Oct 22, 2018
CONTRIBUTING.MD Add link to code guidelines to contributing doc Apr 1, 2016
Dangerfile LGTM reduced to simple markdown Apr 18, 2018
Dockerfile sous server: clone gdm + functional Dockerfile Oct 10, 2016
Gemfile LGTM reduced to simple markdown Apr 18, 2018
Gemfile.lock update Gemfile.lock with newer fpm Aug 27, 2018
Jenkinsfile retry Jul 27, 2018
LICENSE Added MIT license Mar 30, 2016
Makefile mark as integration test Aug 15, 2018 add note to readme about tc links Apr 18, 2018
TODO.txt Could keep refining this. Let's get it released. Sep 14, 2017
Vagrantfile Add Vagrantfile and related. Mar 23, 2018
codecov.yml More codecov ignores. Jun 29, 2017
gemset.nix LGTM reduced to simple markdown Apr 18, 2018
gometalinter.json tweaks for metalinter Feb 14, 2018
logging-notes.txt Documentation comments Sep 14, 2017
main.go Fix scoop, use Exported name, updated changelog Apr 30, 2018
shell.nix Some little cleanups - extending test duration May 17, 2018
staticcheck.ignore Initial pass at updating the difference algorithm Mar 27, 2017
version.go Change VersionString to standard variable. Jan 10, 2017

sous Build Status Report card Floobits Status

Sous is a tool for building, testing, and deploying applications, using Docker, Mesos, and Singularity.

If you just want to use Sous to build and deploy your code, follow the installation instructions.

For contribution guidelines, see here.

Teamcity Links are internal to opentable, please rely on Travis for build statuses from outside opentable.

View documentation in the doc/ directory.

Using Sous

If you're looking to get started using Sous to manage your service within a larger organization, read on.

Bleeding edge development

Sous is written in Go. Once you have Go set up on your machine, you can install it by typing:

$ go get -u -v

However, for normal use, we recommend that you use a release, rather than fritter away development time on our QA. Also, while we'll do our best, we'll be most able to help with bugs on released versions.

Client Configuration

To use Sous effectively, you'll need to know the URL of at least one running Sous server. (If you're looking to set up a new Sous deployment, see this guide.) That URL will be particular to your organization, but someone should be able to provide it to you.

Once you have it, run:

$ sous config server <URL>

(...replacing <URL> with the URL you were given.)

You should be good to go, but if you're curious, client configuration is documented here.

The Installation and Client Configuration steps should only need to be done once on any given workstation.

Hello sous

Now that you have a Sous client set up, let's add a project to Sous management.

The following commands will contact the Sous server and create your project in every known cluster:

# Enter the directory of your project.
$ cd <my-project>

# Connect to the Sous server and register the project's existence.
$ sous init

You can limit this to a single cluster by replacing the last command with sous init -cluster <name>

Sous will provide a list of known clusters if you give it bad input.

To add or remove your project from available clusters, use sous manifest get > manifest.yaml to download the current state of deployments. After editing the returned yaml file, use sous manifest set < manifest.yaml to send the changes to your Sous server.

Since there's no Docker image that corresponds to this project yet, Sous won't actually try to deploy your project yet.

Day to day

From then on, the process is similar, but you don't need to do the sous init since Sous already knows about the project.

Instead, you'll want to use sous deploy, like this:

# Sous requires that projects be tagged with a
# semantic version.
$ git tag -a 1.2.4 -m "sous build tag" && git push --tags

# Actually do the docker build, push and registration steps
$ sous build

# Update Sous' view of the world so that it knows you want to
# deploy the version you built.
$ sous deploy -tag 1.2.4 -cluster <name>

As soon as you've completed the deploy step, Sous will be ready to deploy your service. You should see it deployed and running in a few seconds.

Note that these steps can be easily adapted to work on continuous integrations servers, as well.


Sous shells out to your system to interact with Git and Docker. This is a design decision, as it enables you to easily repeat the commands Sous issues. That means that when they fail, as they sometimes do, you have the power to re-play what happened, and figure out the issue.

You will need:

  • Git >=2.2
  • Go >= 1.7
  • Docker >=1.10

On Mac, we recommend installing Docker by installing docker-machine via the Docker Toolbox available at