What is Swarmlet?
What is Swarmlet?
Swarmlet is a self-hosted, open-source Platform as a Service that runs on any single server. It's mainly intended for use with multiple servers, a server cluster / swarm.
Heavily inspired by Dokku.
It's a piece of software that you can install on a server, enabling you to host apps with ease.
Swarmlet handles the initial server configuration and makes sure apps keep running.
Deploy or update an app by simply
git push-ing your app to your newly created Swarmlet server.
Add additional nodes (servers) to the swarm (server cluster) to provide more resources for your apps.
swarmlet command to perform common tasks on the server.
Swarmlet is a thin wrapper around Docker Compose and Docker Swarm mode.
A few core services, Traefik (v2.3), Let's Encrypt, Ansible and GlusterFS are included by default.
These enable automatic SSL, load balancing, swarm state management and distributed file storage.
Let's Encrypt wildcard certificates support - more info.
This project is aimed at developers that want to experiment with application deployment in a flexible multi-server / high-availability environment. The goal is to be able to set up your own swarm and deploy your app(s) in minutes.
- The project GitHub repository can be found at github.com/swarmlet/swarmlet
- The Swarmlet project boards are located at github.com/orgs/swarmlet/projects
- Join the discussion on Slack using this invite link
Video walkthrough on how to set up a domain and server with Swarmlet from scratch.
We'll deploy 8 apps in under 10 minutes, with each app accessible on it's own (sub)domain.
This demo is outdated, things work roughly the same though.
Please check back in a few weeks for an updated version!
Imagine you want to host multiple applications, websites, API services, databases and workers on your VPS (Virtual Private Server). Docker makes it possible to wrap each application in it's own container so it can be deployed anywhere. A tool like Dokku does a very good job at managing and building these containers on a VPS and having multiple web applications running on the same server. Dokku can manage virtual hosts, enable SSL using Let's Encrypt, handle environment variable injection, etc. And most importantly, Dokku makes it possible to deploy apps to your server with a simple
Now there comes a time when we have 25+ applications running on our single host. Disk space starts becoming an issue, anxiety intensifies about the server going down, you wake up in the middle of the night mumbling "Ephemeral Application Container Orchestration and Continuous Delivery on Highly-Available Server Clusters" and the creeping thought of running a personal server cluster seems to be growing stronger by the day.
"But what about resource allocation in a distributed system?"
"And which server is running my application container?"
"What happens when a server running my website container crashes?"
"Where will my SSL certificates be stored in a swarm with 3 nodes?"
Questions, doubt.. We could just ramp up the server resources a.k.a. scaling vertically. Adding more processing power, disk space or increasing memory. (downtime..) - However, the itching thought of running a multi server setup just feels like the right thing to do. Ok, so what are the options? Everyone is talking about Kubernetes, a bit much to start with maybe. The k3s project looks interesting but since it's based on Kubernetes the learning curve is still quite steep.
Since we're using
docker-compose.yml files in our projects already, let's try to stay close to Docker. It would be nice to stay very close to Docker for maximal compatibility. It would also be nice to be able to define our entire application stack, including domains, deployment strategies, networking and persistent storage for our ephemeral / stateless applications in a single file. Also we want to be able to
git push our local project repository to our cluster to deploy and have SSL certificates issued automatically for our web facing services. You're probably using Docker Compose already, so let's combine Git, Docker Swarm mode and Docker Compose to deploy applications to a flexible (cheap) personal server cluster.
- Install Swarmlet on a new VPS running Ubuntu 18.04 x64 as root.
- Edit your local SSH config to use
ssh swarminstead of
- Use an existing project, or clone one of the examples
- Add a
docker-compose.ymlfile in the root of your project
- Add a git remote:
git remote add swarm git@swarm:my-project
- Deploy your application stack to the swarm using
git push swarm master
Make sure you have a (sub) domain available which is pointed to your server, this is necessary to access the Traefik or Portainer/Matomo dashboards located at e.g.
You can use
dig if you're unsure if your domain points to the right IP address or DNS has updated yet.
From your local machine, run:
dig +short your-domain.com
Quick interactive installation
To install the latest version of Swarmlet, log in to your server as root and run:
curl -fsSL https://get.swarmlet.dev | bash
The installation should take a few minutes to complete.
# Headless (noninteractive) installation:
curl -fsSL https://get.swarmlet.dev | bash -s \
INSTALL_MODULES="matomo swarmpit" \
Swarmlet includes various examples of services that you can deploy to your server cluster with a simple
- swarmlet-website - The swarmlet.dev website
- get-swarmlet - The get.swarmlet.dev install script
- Basic example - Static site
- Basic example - Python web server + Redis
- Moderate example - NGINX + React app + Node.js API
- (FIX) Advanced example - NGINX + React app + Node.js API + CMS + staging/production
- (FIX) GitLab CE (self-hosted)
- (FIX) GitLab Runner (self-hosted)