sadm

Introduction

This repository holds all the files for my personal infrastructure which is currently deployed on the zuh0.com domain name.

Thanks to this repository, it is easy to setup all the services I use with a single command using an Ansible playbook.

If after reading this small documentation you can't manage to use this repository you can check out the Ansible documentation which is a good example of great documentation.

Since the playbook is idempotent and always tries to update packages and Docker images before deploying them, once your server is deployed, maintaining it should be as easy as running the playbook once and a while.

Throughout this documentation we will assume the domain name you want to deploy to is example.com.

A list of services you will get is:

• traefik.example.com - access to your Traefik dashboard

• files.example.com - file sharing service with authentication for upload

• paste.example.com - secure paste service with authentication for upload

• gitlab.example.com - GitLab instance with GitLab pages support, CI docker runners and container registries

• jupyterhub.example.com - JupyterHub instance with authentication using the GitLab accounts through the OAuth2 protocol

• vpn.example.com - WireGuard VPN server with QRcode or plain text configuration generation

All networking passes through the Traefik reverse proxy (even the UDP packets for the VPN and TCP packets for GitLab's SSH) except for the host's SSH which will be available on port 222 which you can use for failure recovery and backup exporting if needed.

Before deploying

You should know a few things before deploying.

I am in no responsible for your infrastructure's failure or management.

Handling mine is already a pain.

To run this playbook you will need a Ubuntu server with an available SSH connection on port 22 or 222 for user root using SSH keys and not passwords.

It looks like my server is using a little under 4GiB of RAM at idle with everything running so I would suggest you use a server with at least 8GiB RAM as GitLab can hog quite a bit of memory, especially when running CI jobs.

You are also going to need DNS records for all the aformentionned domain names (wildcard sounds nice if you are using static DNS and CNAMEs to a dynamic DNS host can work too).

Of course, to use this playbook you will have to install ansible on your local machine.

Also, the playbook sets up a pretty restrictive firewall using UFW so beware, all traffic which is not in the following ports will be dropped:

• 22/TCP

• 80/TCP

• 222/TCP

• 443/TCP

• 51820/UDP

How to deploy

The first thing to do is install the community.general Ansible module package which contains the roles needed to manipulate the Docker API on your server.

You can do this by running:

  $ ansible-galaxy collection install -r requirements.yml

After that you have to change the value of ansible_host in the hosts file. The value you set there can de a domain name or an IP address.

You shouldn't change the ansible_port variable there. The playbook will detect the open port for you so don't worry.

In order to deploy you will have to edit the host_vars/server file to setup the variables you want to (there are comments to tell you what you will probably want to change) and create a secrets file to overwrite the one given with this repository in vaulted_vars/secrets (it is encrypted twice so have fun ;).

A sample secrets file is provided in the examples/secrets file and is commented for you to know how to edit it. Once you have edited it, just put it in examples/secrets and you will be good to go.

One you are setup you can just run:

  $ ansible-playbook sadm.yml

You're done.

To maintain the server by updating everything and pulling in new Docker images you can just run the playbook again with the same command. As the playbook is idempotent you can run it as many times as you want.

By default, all the files generated by services will be in the /sadm folder on your server.

To backup the files for all services a part for the file sharing and paste ones you can just backup the /sadm/persistent folder on the server.

Although that should work fine, you might want to backup the GitLab instance differently in which case you should use the official tool by following the GitLab documentation.

By default, the backups done using the official GitLab tool will be in the /sadm/persistent folder so you're good to go.