Introduction

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.

Swarmlet is a thin wrapper around Docker Compose and Docker Swarm mode.
Traefik, Consul, Let's Encrypt, Matamo, Swarmpit and Swarmprom are included by default.
Swarmlet uses these to provide automatic SSL, load balancing, 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

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. Create a new VPS running Ubuntu 18.04 x64 and log in as root
  2. Install Swarmlet (optionally with some swap if your server has less than 2gb of memory)
  3. Edit your SSH config to be able to use ssh swarm instead of ssh root@123.23.12.123
  4. Use an existing project, or clone one of the examples
  5. Add a docker-compose.yml file in the root of your project: example docker-compose.yml
  6. Add a git remote: git remote add swarm git@swarm:my-project
    (notice the syntax git@<name-configured-in-ssh-config>:<project-name>)
  7. Deploy your application stack to the swarm using git push swarm master
  8. SSL certificates for web facing services are generated automatically using Let's Encrypt
    (assuming you've assigned a domain to your server in your DNS configuration)

Example application setup and deployment guide

Installation

Requirements: Bash 4.0 or higher (run bash --version).

Full installation instructions can be found here
Make sure you have a (sub) domain available which is pointed to your server, this is necessary to access the included dashboards such as Swarmpit or Matomo.

Quick installation

To install the latest version of Swarmlet, log in to your server as root and run:

# Quick (interactive) installation:
curl -fsSL https://get.swarmlet.dev | bash

With 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
# Install a different branch
BRANCH=develop
curl -fsSL https://raw.githubusercontent.com/swarmlet/swarmlet/$BRANCH/install | bash -s \
INSTALL_BRANCH=$BRANCH \
INSTALLATION_TYPE=interactive

The installation should take a few minutes to complete.

Examples

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