Thomas Maurice
2a067a2fe4
* more readme.md content * imported basic roles * commented said basic roles * trimmed down playbooks to be understandable * update requirements.txt deps
89 lines
4.8 KiB
Markdown
89 lines
4.8 KiB
Markdown
# 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
|
|
```
|
|
|
|
:warning: 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 ''
|
|
```
|
|
|
|
:warning: 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](https://stribny.name/blog/ansible-postgresql/) 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](https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-20-04) 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.
|