From 4bbf78f4ea4a7ff8afa99779cd1676cb73c97b68 Mon Sep 17 00:00:00 2001 From: alex Date: Sat, 11 Oct 2025 21:27:30 +0200 Subject: [PATCH] Flesh out documentation --- README.md | 18 +++++++++++------- infrastructure/README.md | 6 ++++++ infrastructure/roles/git/README.md | 14 ++++++-------- infrastructure/roles/users/README.md | 7 +++++-- infrastructure/roles/vaultwarden/README.md | 5 +++++ 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`. -- 2.47.3