Fetching contributors…
Cannot retrieve contributors at this time
235 lines (163 sloc) 7.52 KB

Contributing to Swarm

Want to hack on Swarm? Awesome! Here are instructions to get you started.

Swarm is a part of the Docker project, and follows the same rules and principles. If you're already familiar with the way Docker does things, you'll feel right at home.

Otherwise, go read Docker's contributions guidelines, issue triaging, review process and branches and tags.

Development Environment Setup

Swarm is written in the Go programming language and manages its dependencies using vndr. This guide will walk you through installing Go, forking the Swarm repo, building Swarm from source and contributing pull requests (PRs) back to the Swarm project.

Install git, Go and vndr

If you don't already have git installed, you should install it. For example, on Ubuntu:

sudo apt-get install git

You also need Go 1.7 or higher. Download Go from To install on Linux:

tar xzvf go1.7.1.linux-amd64.tar.gz
sudo mv go /usr/local

Note: On Ubuntu, do not use apt-get to install Go. Its repositories tend to include older versions of Go. Instead, install the latest Go manually using the instructions provided on the Go site.

Create a Go project directory in your home directory:

mkdir ~/gocode    # any name is fine

Add these to your .bashrc:

export GOROOT=/usr/local/go
export GOPATH=~/gocode
export PATH=$PATH:$GOPATH/bin:$GOROOT/bin

Close and reopen your terminal.

Install vndr:

go get

Install golint:

go get

Fork the Swarm repo

You will create a Github fork of the Swarm repository. You will make changes to this fork. When your work is ready for review, open a pull request to contribute the work back to the main Swarm repo.

Go to the docker/swarm repo in a browser and click the "Fork" button in the top right corner. You'll end up with your form of Swarm in<username>/swarm.

(Throughout this document, <username> refers to your Github username.)

Clone Swarm and set remotes

Now clone the main Swarm repo:

mkdir -p $GOPATH/src/
cd $GOPATH/src/
git clone
cd swarm

For the easiest contribution workflow, we will set up remotes as follows:

  • origin is your personal fork
  • upstream is docker/swarm

Run these commands:

git remote remove origin
git remote add origin<username>/swarm.git
git remote add upstream
git remote set-url --push upstream no-pushing

You can check your configuration like this:

$ git remote -v
origin<username>/swarm.git (fetch)
origin<username>/swarm.git (push)
upstream (fetch)
upstream   no-pushing (push)

Pull docker/swarm changes into your fork

As the docker/swarm moves forward, it will accumulate commits that are not in your personal fork. To keep your fork up to date, you need to periodically rebase:

git fetch upstream master
git rebase upstream/master
git push -f origin master

Don't worry: fetching the upstream and rebasing will not overwrite your local changes.

Build the Swarm binary

Build the binary, installing it to $GOPATH/bin/swarm:

cd $GOPATH/src/
go install .

Run the binary you just created:

$GOPATH/bin/swarm help
$GOPATH/bin/swarm create
$GOPATH/bin/swarm manage token://<cluster_id>
$GOPATH/bin/swarm join --addr=<node_ip:2375> token://<cluster_id>

Create a Swarm image for deployment

Swarm is distributed as a Docker image with a single swarm binary inside. To create the image:

docker build -t my_swarm .

Now you can run the same commands as above using the container:

docker run my_swarm help
docker run -d my_swarm join --addr=<node_ip:2375> token://<cluster_id>
docker run -d -p <manager_port>:2375 my_swarm manage token://<cluster_id>

For complete documentation on how to use Swarm, refer to the Swarm section of

Run tests

To run unit tests:

go test -v -race `go list ./... | grep -v /vendor/`

To run integration tests:


You can use this command to check if *.bats files are formatted correctly:

find test/ -type f \( -name "*.sh" -or -name "*.bash" -or -name "*.bats" \) -exec grep -Hn -e "^ " {} \;

You can use this command to check if *.go files are formatted correctly:

golint ./...

Submit a pull request (PR)

Swarm welcomes your contributions back to the project! We follow the same contribution process and principles as other Docker projects. This tutorial describes the Docker contribution workflow.

In general, your contribution workflow for Swarm will look like this:

cd $GOPATH/src/
git checkout master                     # Make sure you have a clean master
git pull upstream master                #   ...before you create your branch.
git checkout -b issue-9999              # Create a branch for your work
vi                            # Edit a file in your branch
git add                       # Git add your changed files
git commit -s -m "Edited README"        # Make a signed commit to your local branch
git push origin issue-9999              # Push your local branch to your fork

To open a PR, browse to your fork at<username>/swarm and select the issue-9999 branch from "Branch" drop down list. Click the green "New Pull Request" button and submit your PR. Maintainers will review your PR and merge it or provide feedback on how to improve it.

Revise your PR

You may receive suggested changes on your PR before it can be merged. If you do, make the changes in the same branch, then do something like:

git checkout issue-9999
git add <changed files>
git commit -s --amend --no-edit
git push -f origin issue-9999

Github will magically update the open PR to add these changes.

Talk to us

The best way to chat with other Swarm developers is on freenode #docker-swarm. (See here for IRC instructions.)

You can also find maintainers' email addresses in MAINTAINERS.

Advanced: Adding New Dependencies

Swarm uses to manage dependencies. If you add a new dependency, say, then to save it, you must add it to vendor.conf with the commit hash. For example: aabc039ad04deb721e234f99cd1b4aa28ac71a40

After this, run vndr to add the relevant files to vendor/. If you need to update existing dependencies, just update the commit hash and run vndr

To make sure you newly added codes will make the build process happy, you can try building Swarm in the same way as defined in Dockerfile.

go install

Then you should find the swarm binary under the $GOBIN directory.

Happy hacking!