A Simplified Approach to Container Orchestration
JavaScript HTML Shell
Latest commit 3799793 Dec 11, 2016 @rusher81572 License
Failed to load latest commit information.
agent fix Dec 9, 2016
docker Adding Sample Docker Files Dec 8, 2016
server fix Dec 11, 2016
systemd fixes Dec 11, 2016
.gitignore adding gitignore Dec 8, 2016
.travis.yml fix Dec 11, 2016
README.md fix Dec 11, 2016
config.json Removing VIP from sample since it is on README Dec 11, 2016
pictl fix Dec 11, 2016



PiCluster is a simple way to manage Docker containers on multiple hosts. I created this because I found Docker Swarm not that good and Kubernetes was too difficult to install currently on ARM. PiCluster will only build and run images from Dockerfile's on the host specified in the config file. This software will work on regular x86 hardware also and is not tied to ARM.

Build Status



  • Run commands in parallel across Nodes
  • Heartbeat for services
  • Easily build and orchestrate Docker images across nodes
  • Command-line interface
  • Web interface
  • HTTP interface
  • Virtual IP Manager


  • Docker
  • Node.js

Server Installation

1. Modify config.json with your desired layout.

This is the core config file for the web console, agent, and server.

You can run the server and agent on the same node since they are listening on different ports.

  "agent_port": "3001",
  "layout": [
    {"node":"", "mysql":"-p 3306:3306","nginx":"-p 80:80"},
    {"node":"", "openvpn":"-p 1194:1194"}],
  "hb": [
    {"node":"","mysql":"3306", "nginx": "80"},
  "vip": [
    {"node":"","vip_eth_device":"eth0", "slave": "", "vip_ping_time": "10000"},
    {"node":"","vip_eth_device":"eth0","slave": "", "vip_ping_time": "15000"}
  "vip_ip": "",
  "automatic_heartbeat": "enabled",
  "heartbeat_interval": "300000",
  "syslog": "dmesg",
  "web_username": "admin",

  • layout - Each row contains an IP address of the node to run the container on, the name for the container image as it corresponds in the Docker folder, and the Docker run arguments.

  • heartbeat - lists the node, container name, and the port to monitor. If the port can not be connected to, PiCluster will restart the failed image.

  • token - A string you define a random string that will be used for authentication with the agents.

  • agent_port - Defines the port that the agent will listen on.

  • docker - Defines where your Dockerfile's are. The format for the Docker folder should be like this: dockerfiles/imagename/Dockerfile

  • web_username and web_password - Define's the username and password for the web interface.

  • web_connect - IP address of a node running the server.

  • web_port - Port that the web console listens on.

  • automatic_heartbeat - Have the server do a heartbeat check on the services in the hb section of config.json. Valid values are: enabled or disabled.

  • heartbeat_interval - How often to do the heartbeat check. Requires automatic_heartbeat to be enabled.

  • syslog - The command used to read the logs on each host.

  • vip - This section contains the agent nodes that the VIP can run on, the ethernet device on each node, and the slave node to run checks against.

  • vip_ping_time - Time in ms to ping each slave. Each host should have different times.

  • vip_ip - The Virtual IP address to use in the cluster

An example on the Docker folder layout:

Based on the config snippet below, I have two container images that will be called "mysql" and "nginx" that will run on host

"layout": [
  {"node":"", "mysql":"-p 3306:3306","nginx":"-p 80:80"}

The Docker folder will need to be setup like this to match the container names:


When it is time to build the containers, PiCluster will use the "docker" variable from config.json plus the container name to locate and build the images.

2. Running the Application

The following environment variables need to be set:

cd server
npm install
node server.js

Agent Installation

The server will send commands to be executed on the agents nodes. The agent should be installed on each host in the cluster.

cd agent
npm install
node agent.js

Web Console Installation

The web console will send commands to the server.

cd web
npm install
node webconsole.js

Configuring and using the client "pictl"

Pictl is a bash client to easily control the cluster. It will make all the HTTP requests using curl.

1. The following variables need to be set in the file:

  • server - IP address of the server
  • port - PORT that the server uses
  • token - The token used in the Server and Agent configs.

2. Using the client

If a command has arguments ([image] or [container]), the commands will run cluster-wide. For example if you run "pictl delete" without specifying a container, all of the containers will be deleted.

To get a list of accepted arguments:


To get a list of all the nodes in PiCluster:

pictl nodes

To build a Docker image from the config:

pictl build [image]

To create and start a container from the config:

pictl create [container]

To stop a container from the config:

pictl stop [container]

To delete a container from the config:

pictl delete [container]

To restart a container from the config:

pictl restart [container]

To execute a command on all of the hosts

pictl exec "command"

Display all of the Docker images on each host

pictl images

To view the current log

pictl log

Using Systemd for Server and Agent Processes

The systemd folder containers the service files and scripts to make PiCluster start at boot time.

1. Modify the .service files in the systemd folder

For each .service file, change ExecStart and ExecStop to reflect the location of the PiCluster folder.

ExecStart=/bin/bash /root/picluster/systemd/start-agent.sh
ExecStop=/bin/bash /root/picluster/systemd/stop-agent.sh

2. Modify the start scripts in the systemd folder

For each file that begins with "start", modify the PICLUSTER_ variables for your installation.

Example for start-agent.sh.

export PICLUSTER_AGENT_PATH="/root/picluster/agent"

3. Copy the systemd files to the systemd directory

cp systemd/*.service /lib/systemd/system/

4. Enable the services

To enable the server service.

systemctl enable picluster-server.service

To enable the agent service.

systemctl enable picluster-agent.service

To enable the web console service.

systemctl enable picluster-web.service

5. Reboot for the services to be started properly


Authors and Contributions

Project created by Phillip Tribble. LinkedIn , Twitter


This work, "Raspy Whale", is a derivative of "raspberry" by Chanut is Industries from the Noun Project used under CC BY, "Sperm Whale" by Oksana Latysheva from the Noun Project used under CC BY, and "Sperm Whale" by Oksana Latysheva from the Noun Project used under CC BY. "Raspy Whale" is licensed under CC BY by Jordan Sinn.