Install Snake Runner with Docker

Snake Runner has been designed with containers in mind. This means that it can be easily started within a container on a host with Docker Engine.

Quick Start

To start a runner, navigate to Bitbucket Admin Panel → Snake CI section → Runners.

Then, click the Copy command button right under the docker run command listing.

Execute the copied command on a Docker host to start the runner. After starting the docker container, you will see a new runner on the Runners page.

Advanced

There are only two parameters required for running Snake Runner:

• the URL of the Bitbucket Server with the Snake CI add-on installed.
• a registration token, which can be found in Bitbucket Admin Panel → Snake CI section → Runners

Docker

Snake Runner is distributed as a Docker image. You can run a standalone container based on the image reconquest/snake-runner.

Installation

Pass the URL of Bitbucket Server and the registration token to docker run command like this:

docker run \
    --name snake-runner \
    --detach \
    --restart on-failure \
    -e "SNAKE_MASTER_ADDRESS=https://<bitbucket-address-here>/" \
    -e "SNAKE_REGISTRATION_TOKEN=<registration-token-here>" \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /var/lib/snake-runner/secrets/:/var/lib/snake-runner/secrets/ \
    reconquest/snake-runner:latest

Note that the address specified in the SNAKE_MASTER_ADDRESS should be accessible from the snake-runner container. For example, if Bitbucket is running in the Docker container on the same host machine, then both containers should be attached to the same Docker network (check --network flag for the docker run command).

Upgrading

1. Stop and remove the existing Snake Runner container:

docker rm -f snake-runner

2. Pull the latest available version of Snake Runner:

docker pull reconquest/snake-runner:latest

3. Run the docker run command from the previous section.

Kubernetes

Requirements: version >= 0.7.0

Installation

Snake Runner can be installed on a Kubernetes cluster using the official Helm chart: reconquest/charts/snake-runner

1. Add the repository:

helm repo add reconquest https://helm.reconquest.io

2. Create your own values.yaml file to override the default values, making sure to specify values in the snake directive:

Key	Description
snake.master_address	The address of Bitbucket with the Snake CI add-on installed. Required
snake.registration_token	The security token for registering the runner. You can obtain it from the Bitbucket admin panel → Runners. Required
snake.docker_mode	Values: “host” or “dind”. “host” means that the runner will mount the host’s docker socket. “dind” stands for docker-in-docker. Required

Check out other possible values.

3. Then, install the runner into the cluster:

# helm 2
helm install --namespace <NAMESPACE> --name ci -f values.yaml reconquest/snake-runner

# helm 3
helm install --namespace <NAMESPACE> ci -f values.yaml reconquest/snake-runner

Upgrading

1. Update the remote chart repository:

helm repo update

2. Upgrade your installation:

helm upgrade -n <NAMESPACE> ci reconquest/snake-runner --force -f values.yaml

Troubleshooting

Don’t see the runner?

• Check the container’s logs:

  docker logs -f snake-runner
  

• Still don’t see anything going wrong and want to debug on your own? Turn on debug or even trace messages by supplying log parameters such as SNAKE_LOG_TRACE=true. These options can be found in the reference.

• Contact us directly or chat with devs on Slack.