add a bunch of READMEs for roles

14 files changed, 62 insertions, 0 deletions

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.