From 301beab91d8f9d16100d1489a575bdb6e8fdd58f Mon Sep 17 00:00:00 2001
From: dogeystamp <dogeystamp@disroot.org>
Date: Sun, 10 Sep 2023 20:56:38 -0400
Subject: [PATCH] README: updated

---
 README.md             | 44 +++++++++++++++++++++++++++++++++++++++++--
 inventory.example.yml |  4 ++++
 2 files changed, 46 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index bb4b469..4491feb 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,49 @@
-## installation steps
+# homeserver ansible playbook
+
+This Ansible playbook allows me to set up and configure all my home lab servers completely automatically, with little to no intervention.
+It is for personal use; do not rely on this for anything important.
+
+Special thanks to [Wolfgang](https://github.com/notthebee/) for the idea of automating the installation process.
+This project was largely inspired by his own [infra](https://github.com/notthebee/infra) repo.
+
+## services
+
+The following services are managed completely automatically:
+- Gitea
+- Matrix Synapse
+- Syncthing
+- Navidrome
+- Exim mail (internal use only)
+- Caddy reverse proxy
+
+## misc features
+
+- Firewall setup (UFW)
+- Python bootstrapping
+- Setting up static IP in LAN
+- External storage decryption/mounting
+- Dotfile installation
+
+## usage
+
+The playbook assumes fresh Arch Linux ARM images installed on machines in your LAN, connected via Ethernet.
+They should start off with default credentials (i.e. `alarm:alarm`, `root:root`).
+This repo takes care of everything else.
+The intended topology is a bastion host facing the Internet, with reverse proxies forwarding traffic to a service host inside the firewall.
+
+- Flash all your machines with Arch Linux ARM.
+- Copy `inventory.example.yml` to `inventory.yml`.
+- Write down the machines' DHCP addresses inside `inventory.yml` under the `fallback_host` field.
+- Assign static LAN IP addresses for your machines in the inventory.
+
+- Set up your domain name and networks.
+    - Forward all needed ports to your bastion host's static IP.
+    - Set up a dynamic DNS subdomain, for example via [nsupdate](https://www.nsupdate.info/).
+    - Create subdomains for Gitea, Matrix, and Navidrome. These should be forwarded to your dynamic DNS subdomain via CNAME records. Configure these subdomains in `group_vars` (see below.)
 
 - Install required packages:
     - sshpass
     - python-passlib
-- Copy `inventory.example.yml` to `inventory.yml`, modifying fields as adequate.
 - Look at `group_vars/all/50-vars.yml`, and set needed settings in `host_vars/<hostname>/vars.yml`, or `group_vars/all/90-overlay.yml`.
     (Files in group vars with a larger number have more precedence.)
 - Look at the following roles, and for each of them override their `defaults/vars.yml` in host or group vars:
diff --git a/inventory.example.yml b/inventory.example.yml
index 661ffb5..e077802 100644
--- a/inventory.example.yml
+++ b/inventory.example.yml
@@ -62,6 +62,10 @@ all:
       hosts:
         your_bastion_host:
         your_fleet_host:
+    mailserver:
+      hosts:
+        your_bastion_host:
+        your_fleet_host:
     website:
       hosts:
         your_bastion_host: