ansible-polytech-2023

This is the repo that will serve as the support for the ASR practical work session of january. You should probably work in this directory and add code to it, it is going to be easier than creating a new ansible repository from scratch. You are also welcome to commit to this repository to checkpoint your work, as well as push it into any repository that polytech gives you access to.

Setup

You will need to install a few things to get started, buckle up.

The virtualenv

Since Ansible is written in python and we don't want to install it in the system, you will need to create a virtual environment. These are used to have your python stuff installed, without making them available system-wide, we are doing this to avoid polluting your lab machine with things that won't be used after today.

To create the virtualenv you need to run the following:

$ python3 -m venv ~/.ansible-venv
# then you want to "activate" the venv, you will need to do this for every new term you open
$ . ~/.ansible-venv/bin/activate

⚠️ you need to run ~/.ansible-venv/bin/activate every time you want to open a new terminal and use ansible in it, otherwise it just won't work because the ansible binary won't be found.

Install ansible

Install ansible via pip after entering the venv

$ pip install -r requirements.txt

At this point you should have ansible installed.

Install the docker role

Install the docker role using ansible galaxy (ansible galaxy is a sort of package manager for ansible).

$ ansible-galaxy install -r requirements.yml

At this point you should be good to go!

Generate an SSH key if you don't have one already

You'll need an SSH key if you don't have one already

If ssh-keygen complains about the key already existing, just reuse the existing key in case someone else needs it.

$ ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -P ''

⚠️ In real life, don't use -P '' because it creates your SSH key without a passphrase, it is ok for this lab, not for real life.

Lastly, look into group_vars/all.yml, go at the end of the file and add the created public key in the root_user.default_root_keys (from ~/.ssh/id_ed25519.pub, or any other keys you created before hand). When this is done, add it to the ~/.ssh/authorized_keys in the root home folder on every one of your virtual machines.

One more thing, update your inventory

You can now update your inventory file by modifying it with your new values (hostnames and ip addresses for the machines you'll be working with).

Read the roles to understand how everything works !

Ansible runs playbooks, which are collections of roles that in turn are a collection of tasks. tasks are instructions like "install this package", "copy this file", "create this directory", "install this service", "create this container" and so on and so forth.

I have very much documented the example roles in ./roles and I would greatly encourage you to read them to understand how to do basic stuff in ansible such as copying a file, starting a service and so on. If you do not do that, you will be lost and won't understand anything that is coming at you.

Check everything works properly

You should now be able to actually run ansible to execute the base.yml playbook.

$ ansible-playbook -vi inventory -l all base.yml

The -i flag specifies the inventory file to use, the -l file limits which hosts it applies to, either by hostname or group name, here we apply it to all the hosts.

While you are at it I would recommend you install docker as well using the docker.yml playbook

Good, now you are good to go !

Install a database server

To deploy Synapse and Mastodon, you need to deploy a database server. We are going to use Postgres in this lab. You will for this need to use the community.postgres_db module for this. The community.* modules are modules written by the community and available to everyone, you will encounter similar modules when you will want to start deploying docker container!

For more details to do this, I refer you to this link which will walk you through how to deal with this.

Create a certificate for our deployments

We need to use a certificate to secure HTTPS communication, both the Mastodon and Matrix protocols require it. This can be done manually for the moment and automated later, as it is not super straightforward. I refer you to the documentation on certbot + nginx I would recommend that you create a mastodon.<yourdomain> and a matrix.<yourdomain> certificate, then back them up somewhere safe as Letsencrypt has pretty aggressive rate limiting with regard to certificate creations.