{"id":13666887,"url":"https://github.com/aelsabbahy/miniswarm","last_synced_at":"2026-01-16T20:51:32.757Z","repository":{"id":144868727,"uuid":"65159395","full_name":"aelsabbahy/miniswarm","owner":"aelsabbahy","description":"Docker Swarm cluster in one command","archived":false,"fork":false,"pushed_at":"2017-12-21T22:43:39.000Z","size":30,"stargazers_count":129,"open_issues_count":1,"forks_count":18,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-11-11T01:35:17.344Z","etag":null,"topics":["cluster","containers","docker","docker-swarm","swarm","swarm-cluster","tutorial"],"latest_commit_sha":null,"homepage":"https://youtu.be/in1ItGKDr98","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aelsabbahy.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}},"created_at":"2016-08-07T23:48:58.000Z","updated_at":"2023-12-10T10:28:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"6934ef5e-4300-49cf-bec3-f7c2e0b7fc62","html_url":"https://github.com/aelsabbahy/miniswarm","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aelsabbahy%2Fminiswarm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aelsabbahy%2Fminiswarm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aelsabbahy%2Fminiswarm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aelsabbahy%2Fminiswarm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aelsabbahy","download_url":"https://codeload.github.com/aelsabbahy/miniswarm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250986528,"owners_count":21518531,"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":["cluster","containers","docker","docker-swarm","swarm","swarm-cluster","tutorial"],"created_at":"2024-08-02T06:01:30.386Z","updated_at":"2026-01-16T20:51:32.751Z","avatar_url":"https://github.com/aelsabbahy.png","language":"Shell","funding_links":[],"categories":["Tools"],"sub_categories":["Setup"],"readme":"# Miniswarm - Docker Swarm cluster in one command\n\n## One command?\nYup, creating a 3 node cluster is simply:\n```\nminiswarm start 3\n```\nWhen you're done:\n```\nminiswarm delete\n```\n\n## What is Miniswarm?\nMiniswarm is a tool that intends to make creating and managing a local [Docker Swarm](https://docs.docker.com/engine/swarm/) cluster as easy as possible. Miniswarm was inspired by [Minikube](https://github.com/kubernetes/minikube) which does a similar thing for kubernetes clusters. See FAQ below for info on managing a remote Swarm cluster.\n\nThe tool takes less than 10 minutes to learn, see the tutorial section below, or watch this tutorial video:\n* [Miniswarm: Local Docker Swarm Cluster and Docker health check Tutorial](https://youtu.be/in1ItGKDr98)\n\n## Prerequisites\n\n* Docker \u003e= 1.12\n* docker-machine \u003e= 0.7.0\n* VirtualBox - Needed for local cluster, see FAQ for remote Swarm cluster\n\n## Miniswarm: Local Docker Swarm and Docker health check tutorial (less than 10min)\nIn this tutorial we'll install miniswarm, create a Swarm cluster, deploy some apps and learn all the features of miniswarm in the process.\n\n#### Install\n```\n# As root\ncurl -sSL https://raw.githubusercontent.com/aelsabbahy/miniswarm/master/miniswarm -o /usr/local/bin/miniswarm\nchmod +rx /usr/local/bin/miniswarm\n```\n\n#### Start a cluster - Pick your desired size\n```\n# 1 manager 2 workers\nminiswarm start 3\n\n# 1 manager cluster - if you want a smaller cluster\nminiswarm start\n\n# 2 managers 3 workers - nice laptop or desktop :)\nminiswarm start 2 3\n```\nA couple of minutes later, you should get this message\n```\nINFO: Stack starup complete. To connect to your stack, run the following command:\nINFO: eval $(docker-machine env ms-manager0)\n```\n\n#### Visualize your cluster\n\nThis will open a browser with a nice visualization of your Docker Swarm using [docker-swarm-visualizer](https://github.com/ManoMarks/docker-swarm-visualizer)\n```\nminiswarm vis\n```\n\n#### Deploy your first service - This will initially be failing to showcase healtchecks\n\nThis service will be unhealthy due to failing [Goss](https://github.com/aelsabbahy/goss) healthchecks and missing dependencies. See next few steps for how we can debug and remedy this.\n```\n# Connect to your cluster\neval $(docker-machine env ms-manager0)\n\n# Create a network for your service\ndocker network create -d overlay healthyvote_net\n\n# Ensure network is set to driver=overlay, scope=swarm\ndocker network ls\n\n# Create your first service\ndocker service create -p 8080:80 --replicas 2 --network healthyvote_net --name vote aelsabbahy/healthyvote\n```\n\n#### Inspect the service health\n```\n# Wait for the service to finish preparing, but it won't ever be ready due to failing health\ndocker service ls\ndocker service ps vote\n\n# Lets look at the healthchecks using miniswarm\n# -a shows all containers, including exited/failed containers\nminiswarm health vote -a\n```\n\nWe should see something like this:\n```\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q] ======\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q] Start: 2016-08-07 22:39:03.748704565 +0000 UTC\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q] ======\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q] .F\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q]\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q] Failures/Skipped:\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q]\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q] Title: Redis backend is reachable\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q] Meta:\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q]     remedy.1: Deploy redis service if you haven't already\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q]     remedy.2: ctrl-alt-delete\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q]     remedy.3: take a nap aka human ctrl-alt-delete\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q] Addr: tcp://redis:6379: reachable:\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q] Expected\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q]     \u003cbool\u003e: false\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q] to equal\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q]     \u003cbool\u003e: true\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q]\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q] Total Duration: 0.500s\n[ms-worker0 vote.2.630mookf9pnc8dip5hl7yng3q] Count: 2, Failed: 1, Skipped: 0\n```\n\n#### Deploy missing dependencies\n\nLets remedy the healthcheck issue\n\n```\ndocker service create --replicas 1 --network healthyvote_net --name redis redis\n\n# Wait for it to show up in `miniswarm vis` or by using CLI\ndocker service ls\ndocker service ps redis\n\n# Now that redis is deployed, the  vote service should now be running\ndocker service ls\n\n# And the health..\nminiswarm health vote\n```\n\n#### Open service in browser\n```\n# Open app in browser\nminiswarm service vote\n\n# print url, but don't open (--url has to be at the end for now)\nminiswarm service vote --url\n```\n\n#### View the logs\n```\nminiswarm logs vote\n\n# Tail the log file (-f has to be at the end for now)\nminiswarm logs vote -f\n```\n\n#### Scale down your cluster\n```\n# Take a look at `miniswarm vis` GUI to see the services move around as we scale down\nminiswarm scale 2\n```\n\n#### Delete your cluster\n```\nminiswarm delete\n```\n\n# FAQ\n## Can this be used to manage a remote Swarm cluster?\nThe tool was written with local Swarm cluster in mind. That said, it can probably be used to manage a remote Swarm clusters, but that hasn't been tested. Take a look at MACHINE_DRIVER variable at the top of the script.\n\nIn theory, if you set the MACHINE_DRIVER variable to the driver you want + any required variables from the driver itself, see [supported drivers](https://docs.docker.com/machine/drivers/) it should just work. Feel free to submit a pull-request to improve this or add more support.\n\n\n## How do I disable the color output?\n\n```\nMS_NOCOLOR=1 miniswarm ..\n\n# or\nexport MS_NOCOLOR=1\nminiswarm ...\n```\n\n## Does this work on Mac/OSX?\nIt should, but I don't own a Mac, so I depend on others to verify it. So.. if something is broke on mac, please submit a pull request.\n\n## Why did you use Goss for healthchecks?\nMostly shameless self-promotion, and while we're on the topic, check out:\n* [Goss](https://github.com/aelsabbahy/goss) - Project page\n* [blog post](https://medium.com/@aelsabbahy/docker-1-12-kubernetes-simplified-health-checks-and-container-ordering-with-goss-fa8debbe676c) - Using Goss with Docker healthchecks and Kubernetes\n\n## Why the #$@^%$ is this written in Bash?\n\nTwo reasons:\n\n1. I though it was going to be ~100 lines of bash, I was wrong.. very wrong :(.\n2. I want users to be able to look at this script and see all the commands needed to set up a Swarm cluster.\n  * Go would be great for this tool, especially by leveraging the Docker go packages directly, but then the tool will be more of a blackbox to new users\n\n## I'm getting intermittent network issues, why is this happening?\nHonestly, I don't know.. I see them too. Either I'm doing something dumb, or Docker Swarm mode has intermittent DNS issues. Hopefully with more users we can get to the bottom of this.\n\n## Why is healthyvote not a Docker automated build?\nBecause Dockerhub doesn't support HEALTHCHECK in Dockerfile yet. The code for this image can be found in the [healthyvote/](https://github.com/aelsabbahy/miniswarm/tree/master/healthyvote) folder.\n\n## Why does this suck?\n\nBecause it's a quick hack I did over the weekend.. or I suck.. maybe both?\n\n## I tried to use it and got an error\n\nOpen an issue, create a pull request.. contribute! :)\n\n## Why is the CLI parsing so bad?\n\nSee the last two questions.\n\n## Social Media:\n* [![Twitter Follow](https://img.shields.io/twitter/follow/aelsabbahy1.svg?style=social\u0026label=Follow\u0026maxAge=2592000)]() - Stay updated on new releases\n* [![Twitter URL](https://img.shields.io/twitter/url/http/shields.io.svg?style=social\u0026maxAge=2592000)](https://twitter.com/intent/tweet?text=Check%20out%20Miniswarm%3A%20Docker%20Swarm%20cluster%20in%20one%20command%20https%3A%2F%2Fgithub.com%2Faelsabbahy%2Fminiswarm%20%23devops%20%23docker) - If you like miniswarm, spread the word!\n* [Blog](https://medium.com/@aelsabbahy) - See what I'm ranting about\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faelsabbahy%2Fminiswarm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faelsabbahy%2Fminiswarm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faelsabbahy%2Fminiswarm/lists"}