Getting started

Standing up your own spin-docker server locally or in the cloud takes minutes. Setup also includes the PostgreSQL, MongoDB, and Django spin-docker images.

Grabbing the source

First download the spin-docker source code - either by cloning the repository on GitHub or downloading and extracting the current version.

Whether you want to run spin-docker in a local virtual machine or on a server, you need Ansible to provision it. Installing Ansible is easy. You can download the source, get it from apt or yum, or just use pip:

$ sudo pip install ansible

Running locally with Vagrant

The easiest way to run spin-docker is using a local virtual machine with Vagrant.

Install Vagrant using the instructions on their site. Like those instructions, this guide will also assume you’re using Virtualbox as your provider.

Before you start your virtual server, add this environment variable to your session if you want your spin-docker containers to be accessible outside of your virtual machine:


Now cd into your spin-docker code and start the vagrant box with vagrant up. Vagrant will download Phusion’s docker-ready Ubuntu 12.04 server box and run an ansible playbook to install and configure spin-docker.


If you get a vagrant error when starting your box saying that some forwarded ports are unavailable, you will need to quit the application that’s using them. I’ve noticed that Chrome in particular can sit on ports around 49200. Quitting Chrome, starting the vagrant box, and then starting Chrome again usually works for me.

Once the vagrant box is running, you can use vagrant ssh to get in and poke around. If you’re ready to learn more about spin-docker, check out the API documentation or Administering spin-docker.

Deploying to a server using Ansible

Spin-docker comes with a complete Ansible playbook that can provision any Ubuntu 12.04 server to run spin-docker. DigitalOcean and Amazon EC2 are always good choices.

Once you have an Ubuntu 12.04 server ready, edit the hosts file in the ansible_playbook subdirectory and add the correct hostname, SSH user, and SSH key for your server. vagrant_box=False ansible_ssh_user=ubuntu ansible_ssh_private_key_file=/Users/atbaker/.ssh/foo.pem

Take care not to accidentally delete the vagrant_box=False variable.

Now you’re ready to run the Ansible play to install and configure spin-docker:

$ ansible-playbook -i hosts spin_docker.yml

Ansible will upgrade the linux kernel, install docker, and install spin-docker with its dependencies. It will also pull down the spin-docker PostgreSQL, MongoDB, and Django images from the docker registry so you can start using the server immediately.


Keep an eye on your server resources. If you’re running spin-docker on an AWS micro instance, for example, you may experience issues running more than one container. Using the ephemeral instance storage as additional swap space can help:

When you’re ready to learn more about spin-docker, check out the API documentation or Administering spin-docker.

Disabling container monitoring

By default spin-docker is configured to stop idle containers after two and a half hours. You may want to disable this feature if you don’t want to adapt your containers to report their activity to spin-docker.

To do this, edit the spin_docker.yaml file in the ansible_playbook directory. Set the sd_disable_timeouts variable to False:

sd_disable_timeouts: False

Then reprovision your spin-docker server. If you’re using vagrant, run vagrant provision. If you’re running your own server run ansible-playbook -i hosts spin_docker.yml.

Learn more about how spin-docker monitors container activity by reading Activity monitoring.