Skip to main content

Introduction

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.


Simply put

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.
Use the swarmlet command to perform common tasks on the server.

> More on how Swarmlet works

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.

During the installation you can choose to install Matamo, Portainer, Swarmpit and Swarmprom.
These optional services are included to provide analytics and various metrics dashboards.

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.

Demo​

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.

TODO

This demo is outdated, things work roughly the same though.
Please check back in a few weeks for an updated version!

Motivation​

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 git push.
Quite amazing.

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 Dockerfile's and 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.

Getting started​

  1. Install Swarmlet on a new VPS running Ubuntu 18.04 x64 as root.
  2. Edit your local SSH config to use ssh swarm instead of ssh root@123.23.12.123
  3. Use an existing project, or clone one of the examples
  4. Add a docker-compose.yml file in the root of your project
  5. Add a git remote: git remote add swarm git@swarm:my-project
  6. Deploy your application stack to the swarm using git push swarm master

Example application setup and deployment guide

Installation​

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. portainer.your-domain.com.

Configure a domain

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.

Full installation instructions can be found here

Custom installation (options)​

# Headless (noninteractive) installation:
curl -fsSL https://get.swarmlet.dev | bash -s \
  INSTALLATION_TYPE=noninteractive \
  INSTALL_ZSH=true \
  CREATE_SWAP=true \
  INSTALL_MODULES="matomo swarmpit" \
  NEW_HOSTNAME=swarm-manager-1 \
  SWARMLET_USERNAME=admin \
  SWARMLET_PASSWORD=nicepassword \
  ROOT_DOMAIN=dev.mydomain.com

Examples​

Swarmlet includes various examples of services that you can deploy to your server cluster with a simple git push.