Flesh out documentation

5 files changed, 33 insertions, 17 deletions

diff --git a/README.md b/README.md
index a731f55..9340e99 100644
--- a/README.md
+++ b/README.md
@@ -2,13 +2,12 @@
 
 ([`xn--ix-yja.es`](https://xn--ix-yja.es) es [ñix.es](https://ñix.es) en punycode.)
 
-Si lees esto y te interesa, por favor escríbeme a alex arroba corcoles punto net o usa los mecanismos de interacción de GitHub (issues, PRs, discusiones).
+Si lees esto y te interesa, por favor escríbeme a alex arroba corcoles punto net.
 
 ñix.es quiere ser una comunidad autogobernada para gente relacionada con la informática en España.
 
 Nota importante: si hay comunidades existentes operativas, igual es mejor incorporarse a ellas.
-Si lees esto y crees que hay posibilidad de alinearse con algo existente, ¡es un plan fantástico!
-Hacedme saber si tengo que mirar algo que no conozco.
+Si lees esto y crees que hay posibilidad de alinearse con algo existente, ¡házmelo saber!
 
 Aunque soy miembro de bastantes comunidades online, la mayoría son o internacionales o anglosajonas; me falta una comunidad más local.
 Creo que hay muchos síntomas de que nos faltan comunidades:
@@ -16,11 +15,16 @@ Creo que hay muchos síntomas de que nos faltan comunidades:
 * Se masca el descontento con las redes sociales comerciales y la nostalgia por las antiguas comunidades de Internet.
 * Hay gente que usa los LLMs para discutir ideas, quizá porque no sienten que tengan gente con la que hablar.
 
-La idea es que los miembros de ñix.es decidan los objetivos de la comunidad, pero una propuesta inicial sería:
+Ahora mismo ñix.es es un VPS corriendo Debian gestionado con Ansible.
+El directorio [`infrastructure`](infrastructure/) contiene los playbooks con los que está instalado.
+La idea es que todos los miembros de ñix.es puedan modificar y ejecutar los playbooks.
 
-1. Facilitar la comunicación entre miembros de la comunidad.
-2. Llevar iniciativas para beneficio de la propia comunidad u otros colectivos.
-3. Difundir lo aprendido para ayudar a crear otras comunidades autogobernadas.
+ñix.es proporciona los siguientes servicios:
+
+* Publicación de repositorios Git con gitweb y https
+* Vaultwarden para almacenar secretos
+
+## Otros
 
 * [Ideas sobre organización](ideas-sobre-organizacion.md)
 * [Posibles iniciativas](posibles-iniciativas.md)
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`.