From dc4dc69b820b1c598eb5de0b26d2e43fb9dc59f8 Mon Sep 17 00:00:00 2001 From: Egor Tensin Date: Mon, 14 Aug 2023 02:38:27 +0200 Subject: add a bunch of READMEs for roles --- roles/apt/README.md | 4 ++++ roles/cloud_init_wait/README.md | 4 ++++ roles/debian_ppa/README.md | 2 ++ roles/digitalocean_volume/README.md | 2 ++ roles/docker/README.md | 2 ++ roles/firewall/README.md | 7 +++++++ roles/journald/README.md | 2 ++ roles/letsencrypt/README.md | 15 +++++++++++++++ roles/linux_status/README.md | 3 +++ roles/router/README.md | 2 ++ roles/systemd_edit/README.md | 3 +++ roles/systemd_requires_mounts_for/README.md | 2 ++ roles/wireguard/README.md | 6 ++++++ roles/workspace/README.md | 8 ++++++++ 14 files changed, 62 insertions(+) create mode 100644 roles/apt/README.md create mode 100644 roles/cloud_init_wait/README.md create mode 100644 roles/debian_ppa/README.md create mode 100644 roles/digitalocean_volume/README.md create mode 100644 roles/docker/README.md create mode 100644 roles/firewall/README.md create mode 100644 roles/journald/README.md create mode 100644 roles/letsencrypt/README.md create mode 100644 roles/linux_status/README.md create mode 100644 roles/router/README.md create mode 100644 roles/systemd_edit/README.md create mode 100644 roles/systemd_requires_mounts_for/README.md create mode 100644 roles/wireguard/README.md create mode 100644 roles/workspace/README.md diff --git a/roles/apt/README.md b/roles/apt/README.md new file mode 100644 index 0000000..ba2b863 --- /dev/null +++ b/roles/apt/README.md @@ -0,0 +1,4 @@ +* Upgrade all installed packages (apt dist-upgrade). +* Clean up dependencies that are no longer needed (apt autoremove). +* Install any additional apt packages required on this host. +* If required, configure unattended-upgrades to install latest security fixes. diff --git a/roles/cloud_init_wait/README.md b/roles/cloud_init_wait/README.md new file mode 100644 index 0000000..ecc034e --- /dev/null +++ b/roles/cloud_init_wait/README.md @@ -0,0 +1,4 @@ +This role is used to wait until cloud-init is done initializing an instance. +This is supposed to be the first role in a playbook; it is advisable to disable +facts gathering so that the playbook can wait until a connection is +established. diff --git a/roles/debian_ppa/README.md b/roles/debian_ppa/README.md new file mode 100644 index 0000000..310404f --- /dev/null +++ b/roles/debian_ppa/README.md @@ -0,0 +1,2 @@ +This role is used to enable an Ubuntu PPA repository on Debian. It downloads +the repository key and adds the repository in /etc/apt/sources.list.d. diff --git a/roles/digitalocean_volume/README.md b/roles/digitalocean_volume/README.md new file mode 100644 index 0000000..7482683 --- /dev/null +++ b/roles/digitalocean_volume/README.md @@ -0,0 +1,2 @@ +This role mounts a DigitalOcean data volume in /mnt and adds a corresponding +record in /etc/fstab. diff --git a/roles/docker/README.md b/roles/docker/README.md new file mode 100644 index 0000000..9924691 --- /dev/null +++ b/roles/docker/README.md @@ -0,0 +1,2 @@ +* Install the Docker engine and docker-compose. +* Clean up Docker data (docker system prune). diff --git a/roles/firewall/README.md b/roles/firewall/README.md new file mode 100644 index 0000000..9c1a572 --- /dev/null +++ b/roles/firewall/README.md @@ -0,0 +1,7 @@ +This role configures iptables rules in /etc/iptables/rules.v{4,6} to be used by +iptables-persistent. + +I found it easier and more flexible to configure a firewall this way; for +example, I found that cloud provider's firewalls are often less flexible. +iptables frontends like ufw, on the other hand, are hard to make work with +Docker. diff --git a/roles/journald/README.md b/roles/journald/README.md new file mode 100644 index 0000000..96a1ba8 --- /dev/null +++ b/roles/journald/README.md @@ -0,0 +1,2 @@ +This role makes the systemd journal less noisy by raising the default log +level. diff --git a/roles/letsencrypt/README.md b/roles/letsencrypt/README.md new file mode 100644 index 0000000..50ca0f6 --- /dev/null +++ b/roles/letsencrypt/README.md @@ -0,0 +1,15 @@ +This role installs certbot and requests certificates from Let's Encrypt. + +It uses the [DNS-01 challenge type] instead of the usual thing where it puts +a file in your web server's root directory. That way, you don't need to launch +the web server at all to obtain the certificates; most often, the configured +web server would fail to start at all at first launch since the certificates +are missing. + +[DNS-01 challenge type]: https://letsencrypt.org/docs/challenge-types/ + +Using the DNS challenge, the certificates are obtained before starting the web +server for the first time, which avoids tinkering with its configuration. It +does come with some downsides: namely, this role explicitly uses certbot's +DigitalOcean plugin, (because I use DO for my domains); and the access token is +stored in a .ini file in /root. diff --git a/roles/linux_status/README.md b/roles/linux_status/README.md new file mode 100644 index 0000000..4c7b128 --- /dev/null +++ b/roles/linux_status/README.md @@ -0,0 +1,3 @@ +This role installs [linux-status] on a Debian server. + +[linux-status]: https://github.com/egor-tensin/linux-status diff --git a/roles/router/README.md b/roles/router/README.md new file mode 100644 index 0000000..2b97976 --- /dev/null +++ b/roles/router/README.md @@ -0,0 +1,2 @@ +This role sets some common sysctl values required for forwarding traffic (which +is a must if the host acts like a router). diff --git a/roles/systemd_edit/README.md b/roles/systemd_edit/README.md new file mode 100644 index 0000000..23af7c8 --- /dev/null +++ b/roles/systemd_edit/README.md @@ -0,0 +1,3 @@ +This role is similar to running `systemctl edit SERVICE`; it creates an +override.conf file for the service in /etc/systemd and sets the required +values there. diff --git a/roles/systemd_requires_mounts_for/README.md b/roles/systemd_requires_mounts_for/README.md new file mode 100644 index 0000000..7aef90f --- /dev/null +++ b/roles/systemd_requires_mounts_for/README.md @@ -0,0 +1,2 @@ +This role modifies a systemd service to require a mounted directory before +starting it. diff --git a/roles/wireguard/README.md b/roles/wireguard/README.md new file mode 100644 index 0000000..47b8091 --- /dev/null +++ b/roles/wireguard/README.md @@ -0,0 +1,6 @@ +This role configures a WireGuard interface using wireguard-tools and the +wg-quick systemd service. + +It accepts the interface name, the private key and a list of peers; see the +template file to discover what parameters are supported. I use it to set up all +of my WireGuard servers. diff --git a/roles/workspace/README.md b/roles/workspace/README.md new file mode 100644 index 0000000..44af085 --- /dev/null +++ b/roles/workspace/README.md @@ -0,0 +1,8 @@ +This role is the most specialized and opinionated of all. It can be used to +clone a bunch of repositories to /srv/workspace; it then tries to run either +`make` or `docker-compose up -d` in each of these repositories, which are +called "projects". + +This is how my web "projects" are set up; typically, a project is a repository +with a Makefile which calls docker-compose in a bunch of sub-directories. This +feels like a lame hack, but has worked pretty well so far. -- cgit v1.2.3