From 4bbf78f4ea4a7ff8afa99779cd1676cb73c97b68 Mon Sep 17 00:00:00 2001
From: alex <alex@pdp7.net>
Date: Sat, 11 Oct 2025 21:27:30 +0200
Subject: Flesh out documentation

---
 infrastructure/README.md                   |  6 ++++++
 infrastructure/roles/git/README.md         | 14 ++++++--------
 infrastructure/roles/users/README.md       |  7 +++++--
 infrastructure/roles/vaultwarden/README.md |  5 +++++
 4 files changed, 22 insertions(+), 10 deletions(-)

(limited to 'infrastructure')

diff --git a/infrastructure/README.md b/infrastructure/README.md
index 4694334..757152a 100644
--- a/infrastructure/README.md
+++ b/infrastructure/README.md
@@ -29,6 +29,12 @@ After [setting your user password](roles/users/README.md):
 uv run ansible-playbook -K -i production.yaml site.yaml
 ```
 
+## Roles
+
+* The [users](roles/users) role to add new users
+* The [git](roles/git) role to host Git repositories (https and Gitweb)
+* The [vaultwarden](roles/vaultwarden) role for secret management
+
 ## Notes
 
 ### Contabo Debian 13
diff --git a/infrastructure/roles/git/README.md b/infrastructure/roles/git/README.md
index f21bfef..90a558d 100644
--- a/infrastructure/roles/git/README.md
+++ b/infrastructure/roles/git/README.md
@@ -5,29 +5,27 @@
 On the server:
 
 ```
-git init --bare $REPO
+git init --bare $REPOSITORY_PATH
 ```
 
 ## Push an existing repository
 
 ```
-git remote add $REMOTE_NAME $SERVER:$REPO
-git push $REMOTE_NAME main
+git remote add $REMOTE $SERVER_HOSTNAME:$REPOSITORY_PATH
+git push $REMOTE main
 ```
 
 ## Exposing via gitweb
 
 ```
-sudo ln -s $ABSOLUTE_PATH_TO_REPO /var/lib/git/$NAME.git
+sudo ln -s $REPOSITORY_PATH /var/lib/git/$NAME.git
 ```
 
-You can use `~/foo` as the `ABSOLUTE_PATH_TO_REPO` to expose a repository in your home directory.
-
 ## Exposing via https
 
 ```
-mv $ABSOLUTE_PATH_TO_REPO/hooks/post-update.sample $ABSOLUTE_PATH_TO_REPO/hooks/post-update
-ln -s $ABSOLUTE_PATH_TO_REPO ~/public_html/$REPO.git
+mv $REPOSITORY_PATH/hooks/post-update.sample $REPOSITORY_PATH/hooks/post-update
+ln -s $REPOSITORY_PATH ~/public_html/$REPO.git
 ```
 
 Ensure that you push once to the repo, or run `git update-server-info` in the repository.
diff --git a/infrastructure/roles/users/README.md b/infrastructure/roles/users/README.md
index 3741ff1..a1ad1ea 100644
--- a/infrastructure/roles/users/README.md
+++ b/infrastructure/roles/users/README.md
@@ -1,11 +1,14 @@
 # Users
 
-## Initial set up
+## Creating users
+
+This role creates users described in the [production](../../production.yaml) inventory.
+Change this file to create new users.
 
 This role creates users in the `sudo` group.
 `sudo` requires a password.
 
-To set your password, run `su -c "passwd $(whoami)"`.
+Once you can ssh to your user, set your password with `su -c "passwd $(whoami)"`.
 
 From then on, use `sudo` for privileged actions.
 Remember to only modify the system using Ansible.
diff --git a/infrastructure/roles/vaultwarden/README.md b/infrastructure/roles/vaultwarden/README.md
index e899348..ad689cc 100644
--- a/infrastructure/roles/vaultwarden/README.md
+++ b/infrastructure/roles/vaultwarden/README.md
@@ -1,5 +1,10 @@
 # Vaultwarden
 
+## Registering to Vaultwarden
+
+Registration is limited to the `@localhost` domain so that only local users can register.
+Registration requires email validation.
+
 Visit `/vaultwarden`, select "create account", then use `$USER@localhost` as your email address.
 
 1. Run `mutt`.
-- 
cgit v1.2.3