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.
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.
If you don't already have git
installed, you should install it. For example, on Ubuntu:
sudo apt-get install git
Download Go from https://golang.org/dl/. To install on Linux:
tar xzvf go1.12.4.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 github.com/LK4d4/vndr
Install golint:
go get golang.org/x/lint/golint
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 https://github.com/<username>/swarm
.
(Throughout this document, <username>
refers to your Github username.)
Now clone the main Swarm repo:
mkdir -p $GOPATH/src/github.com/docker
cd $GOPATH/src/github.com/docker
git clone https://github.com/docker/swarm.git
cd swarm
For the easiest contribution workflow, we will set up remotes as follows:
origin
is your personal forkupstream
isdocker/swarm
Run these commands:
git remote remove origin
git remote add origin https://github.com/<username>/swarm.git
git remote add upstream https://github.com/docker/swarm.git
git remote set-url --push upstream no-pushing
You can check your configuration like this:
$ git remote -v
origin https://github.com/<username>/swarm.git (fetch)
origin https://github.com/<username>/swarm.git (push)
upstream https://github.com/docker/swarm.git (fetch)
upstream no-pushing (push)
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 binary, installing it to $GOPATH/bin/swarm
:
cd $GOPATH/src/github.com/docker/swarm
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>
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 docs.docker.com.
To run unit tests:
go test -v -race `go list ./... | grep -v /vendor/`
To run integration tests:
./test/integration/run.sh
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 ./...
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/github.com/docker/swarm
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 README.md # Edit a file in your branch
git add README.md # 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 http://github.com/<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.
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.
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
.
Swarm uses github.com/LK4D4/vndr
to manage dependencies. If you add a new dependency, say github.com/new/dependency
, then to save it, you must add it to vendor.conf
with the commit hash. For example:
github.com/new/dependency aabc039ad04deb721e234f99cd1b4aa28ac71a40
After this, run vndr github.com/new/dependency
to add the relevant files to vendor/
. If you need to update existing dependencies, just update the commit hash and run vndr github.com/existing/dependency
.
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!