diff --git a/README.md b/README.md index 916a919..6bda70f 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,40 @@ Sistema de autenticación basado en Keycloak, que permite que un usuario que acc ## Instalación y ejecución +El proyecto solamente necesita un motor de contenedores (actualmente Docker) y que se habiliten las `units` de `systemd` para que se ejecute periódicamente el servicio de renovación de certificados de _Let's Encrypt_. + ### Crear el espacio de trabajo +Copia el contenido de este repositorio sobre el directorio de instalación de tu preferencia. Los scripts están preparados para trabajar desde `/opt`, por lo que si escoges instalar en otra ubicación, deberás modificar los ficheros `docker-compose.yaml`, `certbot/certbot-keycloak.service` y `certbot/certbot-keycloak.sh` a conveniencia. + ### Configuración #### Keycloak +El servicio de _Keycloak_ se inicia con `docker-compose`. Antes de la ejecución, rellena las variables de configuración necesarias. Hay una plantilla de ejemplo en `.env-sample`. Utiliza esa plantilla como base y guárdala con el nombre `.env`. Dentro encontrarás las variables de configuración que se utilizan en el fichero de `docker-compose`. Ajústalas como corresponda. + #### Certbot -### Scripts de inicio \ No newline at end of file +_Keycloak_ ejecuta en un contenedor no accesible desde internet y sin usar cifrado, para permitir que las personas que administran el servicio puedan capturar tráfico y depurar problemas del servicio, en caso necesario. + +De cara a internet, el servicio se ofrece tras un proxy NGINX, que hace de terminador TLS. El certificado que se requiere para ello se genera con _Let's Encrypt_ y tiene que renovarse con cierta frecuencia. Se utiliza el contenedor de _Certbot_ para gestionar las renovaciones y el sistema se apoya en un script que copia los certificados nuevos sobre el espacio de trabajo de NGINX para que se utilicen en cuanto se reciben. + +En el directorio de `certbot` hay un subdirectorio `renewal` que contiene un fichero de ejemplo con la configuración que se necesita para la renovación automática. El fichero de ejemplo se llama `acceso.txs.es.conf-sample` y puede servir de plantilla para que configures el real, que deberá llamarse `acceso.txs.es.conf` + +#### Scripts de inicio + +El servicio _Keycloak_ se inicia ejecutando: + +```bash +root@server:/opt$ docker-compose up -d +``` + +Además, hay que instalar y activar las `units` de `systemd` para que el servicio de `certbot` se ejecute periódicamente: + +```bash +root@server:/etc/systemd/system$ ln -s /opt/certbot/certbot-keycloak.service +root@server:/etc/systemd/system$ ln -s /opt/certbot/certbot-keycloak.timer +root@server:/etc/systemd/system$ systemctl daemon-reload +root@server:/etc/systemd/system$ systemctl enable certbot-keycloak.service cerbot-keycloak.timer +root@server:/etc/systemd/system$ systemctl start cerbot-keycloak.timer +```