README.md

Introduction

Lilypad is put together using the float configuration management toolkit for container-based services. It is a series of Ansible plugins and roles glued together to provide a simple container-oriented environment. This can be rolled into your own Ansible configuration, or used separately.

Monitoring, alerting, log-collection and analysis, DNS and Let's Encrypt certificates for all of the services included are handled automatically. Please see the float reference documentation for further details.

Pre-requisites

• Three different machines: reverse-proxy, backend, gateway/s(at least one, more the merrier)

  These can be bare-metal, or virtual machines (eg. KVM). They should have a minimal Debian 12 (Bookworm) installation and be reachable by SSH.

• You will need to pick a subdomain and delegate the DNS to the system to manage.

  For example, if your domain is example.com, then you could delegate the subdomain float.example.com. You would do this on your nameserver or DNS provider: add a NS record for float.example.com that points to ns1.example.com and then an A record for ns1.example.com that points to the IP address you use for the reverse proxy host (note: not the gateway IP).

  like:

Domain	Type	Destination
float.example.com	NS	ns1.example.com
ns1.example.com	A	<IP of ReverseProxy instance>

From now on we will refer to the subdomain (float.example.com in the example) as your service domain.

Architecture

• Reverse Proxy: runs nginx, DNS nameserver and provide the infrastructure front-end.
• Backend: runs the application services that the reverse proxy talks to, it runs, among other things, the LEAP web API, the gateway selection service, and the infrastructure that provides monitoring and alerting.
• Gateway/s: These run openvpn and act as VPN gateways, which ideally require two publicly addressable IP addresses, one for ingress and one for egress.
• Bridge: runs an obfsvpn service, can run on the same machine as the gateway.

How to provision a new provider?

The machines should be considered to be fully managed by this framework when things have been deployed. It will modify the system-level configuration, install packages, start services, etc. However, it assumes that certain functionality is present, either managed manually or with some external mechanisms: network configuration, partitions, file systems, and logical volumes must be externally (or manually) managed. SSH access and configuration must be externally managed unless you explicitly set enable_ssh=true in lilypad/group_vars/all/config.yml (and add SSH keys to your admin users), in which case deployment will take over the SSH configuration.

The following commands should be run locally on your computer in order to install and deploy Lilypad on the remote machines.

0. Clone the float repository

...and enter it

git clone https://0xacab.org/leap/container-platform/lilypad
cd lilypad

1. Install the float and LEAP platform pre-requisites

This installation guide is tested on Debian Bookworm. Other Linux distributions might need additional steps to install all requirements in the correct version.

sudo apt-get install golang build-essential bind9utils git libsodium23 virtualenv

# for golang version lower than 1.16 and use go get instead of go install after running export GO111MODULE=on 

go install git.autistici.org/ale/x509ca@latest
go install git.autistici.org/ale/ed25519gen@latest
go install git.autistici.org/ai3/go-common/cmd/pwtool@latest
export PATH=$PATH:$HOME/go/bin

We'll use virtualenv to manage and install python packages:

virtualenv -p /usr/bin/python3 venv
source ./venv/bin/activate
pip install -r ./requirements.txt