{"id":21126469,"url":"https://github.com/lreimer/raspi-swarm-box","last_synced_at":"2025-07-13T01:10:38.375Z","repository":{"id":71906700,"uuid":"176269674","full_name":"lreimer/raspi-swarm-box","owner":"lreimer","description":"Instructions to build a Raspberry Pi powered Docker Swarm mini cluster in a box.","archived":false,"fork":false,"pushed_at":"2019-04-07T12:18:02.000Z","size":1876,"stargazers_count":19,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-29T21:37:17.899Z","etag":null,"topics":["clusterhat","docker","docker-swarm","raspberry-pi","raspberry-pi-3","raspberry-pi-zero"],"latest_commit_sha":null,"homepage":null,"language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lreimer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-03-18T11:32:24.000Z","updated_at":"2024-05-05T17:50:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"a07521d2-3cc4-4bfa-b7d4-c4e83568aac1","html_url":"https://github.com/lreimer/raspi-swarm-box","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lreimer/raspi-swarm-box","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lreimer%2Fraspi-swarm-box","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lreimer%2Fraspi-swarm-box/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lreimer%2Fraspi-swarm-box/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lreimer%2Fraspi-swarm-box/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lreimer","download_url":"https://codeload.github.com/lreimer/raspi-swarm-box/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lreimer%2Fraspi-swarm-box/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265077176,"owners_count":23707632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clusterhat","docker","docker-swarm","raspberry-pi","raspberry-pi-3","raspberry-pi-zero"],"created_at":"2024-11-20T04:41:59.768Z","updated_at":"2025-07-13T01:10:38.051Z","avatar_url":"https://github.com/lreimer.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Raspberry Swarm Box\n\nInstructions to build a Raspberry Pi powered Docker Swarm mini cluster in a box.\n\n## Bill of Material\n\nWell, first you need to buy the hardware. Here is the list of what I bought.\n\n* Raspberry Pi 3 Model B+ (https://www.modmypi.com/raspberry-pi/set-up-kits/rpi3-model-b-plus-kits/raspberry-pi-3-model-b-plus-and-16gb-microsd-bundle)\n* Cluster HAT Kit Inc. 4 x Raspberry Pi Zero (https://www.modmypi.com/raspberry-pi/iousbanalogue-expansion-1028/interfacing-1080/cluster-hat-kit-inc.-4-x-raspberry-pi-zero)\n* Cluster HAT Case (https://www.modmypi.com/raspberry-pi/cases-183/raspberry-pi-b-plus2-and-3-cases-1122/cases-for-hats-and-boards-1133/cluster-hat-case)\n\n## Assembly\n\nThis is the fun part. Basically unpack everything and put all the parts together.\nHave a look into the `assembly/` directory for more images.\n\n![](assembly/IMG_20190207_134102.jpg)\n\n## Node Setup\n\nThis section is about setting up all five Raspberry Pi nodes with the required software. First up, make sure that you download\nthe Raspbian images from the ClusterHAT website: https://clusterhat.com/setup-software\n\nSince we want the Zero nodes to be able to access the internet, make sure you download the NAT Desktop controller image! Write all\nthe images to a SD card using balenaEtcher or a similar software. Also make sure to insert the appropriate SD card into the right\nRaspi Zero slot.\n\n### Controller Node Setup\n\nOnce switched on, perform the following steps after the first boot\n- following the basic setup instructions (locale, network and wireless LAN, password, update)\n- after the next reboot, open the Raspi configuration in a shell using `sudo rasp-config`\n- make sure you extend the partition to the full size of your SD card!\n- enable SSH\n\nBefore you continue with the following steps, make sure you have performed the basic setup of all four Zero nodes.\nIn a terminal, issue the following commands:\n```\nclusterhat on\n\nssh-keygen\nssh-copy-id -i ~/.ssh/id_rsa pi@172.19.181.1\nssh-copy-id -i ~/.ssh/id_rsa pi@172.19.181.2\nssh-copy-id -i ~/.ssh/id_rsa pi@172.19.181.3\nssh-copy-id -i ~/.ssh/id_rsa pi@172.19.181.4\n```\n\nTo make working with the nodes a little easier, edit your `/etc/hosts` file and add the following:\n```\n172.19.181.254  master cnat\n172.19.181.1    p1\n172.19.181.2    p2\n172.19.181.3    p3\n172.19.181.4    p4\n```\n\nIf you want to develop and compile your Go based services on the controller node, you need to install Go.\n```\nsudo apt-get install -y vim\n\ncd /tmp/\nwget https://dl.google.com/go/go1.12.1.linux-armv6l.tar.gz\n\nsudo mkdir -p /usr/local/go\nsudo tar -xvf /tmp/go1.12.1.linux-armv6l.tar.gz -C /usr/local/go --strip-components=1\n```\n\n### Zero Node Setup\n\nOn the controller node, open a terminal and perform the following commands for each Zero (p1, p2, p3, p4).\nThe user is `pi` and the initial password is `clusterhat`.\n\n```\nclusterhat on p1\nminicom p1\nsudo raspi-config\n```\n\nIn the configuration,\n- make sure you extend the partition to the full size of your SD card!\n- enable SSH\n- change the root password\n- reduce the memory split to 16MB\n- adjust the locale and timezone settings\n- update the system\n\nWhen all changes are done, perform a reboot of the node. You should be able to login via SSH now.\n\n\n## Docker (Swarm) Setup\n\n### Install Docker\n\nThe Docker setup is slightly complicated. The problem is, that the current versions of Docker do not run on the Rasperry Pi Zeros anymore! Make\nsure you follow the Github issue https://github.com/moby/moby/issues/38175 to get the latest status. As of this writing, you need to use 18.06.*\n\n1. On each node, ensure that there is a file `/etc/apt/sources.list.d/docker.list` with the following content, create it otherwise.\n```\ndeb [arch=armhf] https://download.docker.com/linux/raspbian stretch stable\n```\n\n2. On each node, ensure that there is a file `/etc/apt/preferences.d/docker-ce` with the following content, create it otherwise.\n```\nPackage: docker-ce\nPin: version 18.06.*\nPin-Priority: 1000\n```\n\n3. On each node, install the Docker package using:\n```\nsudo apt-get -y install docker-ce=18.06.2~ce~3-0~raspbian\nsudo usermod -aG docker pi\n```\n\n### Create Docker Swarm\n\nFirst, you need to initialize the swarm on the master node. Make sure you use the ClusterHAT internal address.\n```\ndocker swarm init --advertise-addr 172.19.181.254:2377 --listen-addr 172.19.181.254:2377\n```\n\nThen on each of the Zero nodes, login via SSH and issue the command that the previous command echoed _(the token will vary!!!)_, e.g.\n```\ndocker swarm join --token SWMTKN-1-6cx6yq79x459o28kwaipsta7y149o2j6p2g0sxjodil249v0o8-daye1lc9blrh2ba2ojxr6k82v 172.19.181.254:2377\n```\n\nOnce you did this, check the health of your swarm and that all nodes are available.\nWe also label the Zero nodes so that we can later specify placement conditions for our services.\nAlso you can install a visualizer image.\n```\ndocker node list\n\ndocker node update --label-add type=zero p1\ndocker node update --label-add type=zero p2\ndocker node update --label-add type=zero p3\ndocker node update --label-add type=zero p4\n\ndocker service create --name=viz --publish=7070:8080/tcp --constraint=node.role==manager --mount=type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock alexellis2/visualizer-arm:latest\nxdg-open http://master:7070\n```\n\n### Using Docker Swarm\n\n```\ndocker service create --name nginx --publish :80:80 --replicas 1 arm32v6/nginx:1.15.9-alpine\ndocker service scale nginx=4\n\ndocker service create --name alpine --entrypoint sleep 10 --restart-delay 1s --replicas 4 arm32v6/alpine:3.9.2\n\n# pull some useful images if required\ndocker pull arm32v6/traefik:1.7.9\ndocker pull arm32v6/consul:1.4.3\ndocker pull arm32v6/golang:1.12.1-alpine\ndocker pull arm32v6/nats-streaming:0.12.2-linux\ndocker pull arm32v6/postgres:11.2-alpine\ndocker pull arm32v6/nginx:1.15.9-alpine\ndocker pull arm32v6/alpine:3.9.2\ndocker pull arm32v6/node:11.11.0-alpine\ndocker pull arm32v6/eclipse-mosquitto:1.5.8\ndocker pull arm32v6/haproxy:1.9.4-alpine\ndocker pull arm32v6/nats:1.4.1-linux\ndocker pull arm32v6/rabbitmq:3.7-alpine\ndocker pull arm32v6/rabbitmq:3.7-management-alpine\n```\n\n### Troubleshooting\n\nIf you have followed the official Docker setup instructions (`curl -sLSf https://get.docker.com | sudo sh`) and you are facing the problem that\nthe _containerd_ service does not start on your Zero nodes, you need to remove and purge Docker from the system and follow the instructions above.\n```\nsudo apt-get purge docker-ce\nsudo apt autoremove\nsudo rm -rf /var/lib/docker\nsudo reboot\n```\n\nSometimes the Docker service on the Zero nodes does not start properly and hangs. To solve this, start each node individually. Login to each node\nvia SSH one by one and perform a `sudo systemctl restart docker`. Once done, restart the Docker service on the controller node as well. Your swarm\nshould be up and running again.\n\nIf your Docker swarm breaks for unknown reasons, and you want to recreate it, issue `docker swarm leave --force` on each node and master. Once you\nhave done this, create the swarm again using the above instructions.\n\n## OpenFaaS Installation\n\nCurrently, we have to install OpenFaaS on the master node, because all images need _armhf_ architecture.\nThe `openfaas/docker-compose.armhf.yml` file has been modified so that no service is placed on one of\nthe four Zero nodes which have an `armv6l` architecture.\n```\nmake openfaas-sources openfaas-install\n\necho \"admin\" | docker secret create basic-auth-user -\necho \"admin\" | docker secret create basic-auth-password -\n\nexport BASIC_AUTH=\"true\"\ndocker stack deploy openfaas --compose-file openfaas/docker-compose.armhf.yml\n```\n\n### Running OpenFaas functions\n\n\n\n\n## Maintainer\n\nM.-Leander Reimer (@lreimer), \u003cmario-leander.reimer@qaware.de\u003e\n\n## License\n\nThis software is provided under the MIT open source license, read the `LICENSE`\nfile for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flreimer%2Fraspi-swarm-box","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flreimer%2Fraspi-swarm-box","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flreimer%2Fraspi-swarm-box/lists"}