# Despliegue — sitio, backend de actas y usuarios

Servidor: `git.helgen.online` · dominio público: `https://drogheda.helgen.online`

## Qué vive dónde

| Parte | Ruta en el servidor | Cómo se actualiza |
|---|---|---|
| Sitio (docs, formularios, tableros) | `/srv/projects/drogheda/hbox-docs/site` | `./scripts/deploy.sh` desde la Mac |
| Backend de actas (`app.py`) | `/srv/projects/drogheda/hbox-docs/backend` | `git pull` en el servidor + `systemctl restart actas-hbox` |
| Actas recibidas (JSON + índice CSV) | `/srv/projects/drogheda/actas` | las escribe el backend |
| **Fotos de campo** | `/srv/projects/drogheda/adjuntos` | las escribe el backend — **nuevo** |
| Usuarios (HTTP Basic) | `/etc/nginx/hbox-docs.htpasswd` | `htpasswd` |

**Lo importante:** `deploy.sh` publica **solo el sitio**. Si cambió `backend/app.py` —como en esta
versión— hay que hacer además el `git pull` + `restart` en el servidor, o el sitio nuevo hablará
con un backend viejo (las fotos darían 404 y el diagnóstico se bloquearía como si fuera un acta
de banco).

---

## A · Despliegue de esta versión (diagnóstico en campo)

Los pasos 3, 4 y 5 son **de una sola vez**; los pasos 1 y 2 son el ciclo normal de siempre.

### 1 · Desde la Mac — publicar el sitio

```bash
cd ~/Documents/Claude/Projects/Drogheda/hbox-docs
git add -A && git commit -m "diagnóstico en campo: acta, fotos, tablero y procedimiento"
git push
./scripts/deploy.sh                 # mkdocs build --strict + rsync a /srv/.../site
```

### 2 · En el servidor — actualizar el backend

```bash
cd /srv/projects/drogheda/hbox-docs && git pull
sudo systemctl restart actas-hbox
curl -s http://127.0.0.1:8081/api/salud        # {"ok":true,"servicio":"actas-hbox"}
```

### 3 · Carpeta de fotos (una sola vez)

```bash
sudo mkdir -p /srv/projects/drogheda/adjuntos
sudo chown -R leo:leo /srv/projects/drogheda/adjuntos
```

El backend la deduce sola de `ACTAS_DIR`; si prefieres fijarla, agrega a
`/etc/systemd/system/actas-hbox.service` (y luego `daemon-reload` + `restart`):

```ini
Environment=ADJUNTOS_DIR=/srv/projects/drogheda/adjuntos
Environment=ADJUNTO_MAX_MB=8
Environment=ARCHIVO_MAX_MB=20
Environment=ACTAS_REPETIBLES=diagnostico-campo,instalacion-campo
```

### 4 · nginx — subida de fotos e identidad del técnico (una sola vez)

En el bloque `server { listen 443 … }` de `drogheda.helgen.online`, el `location /api/` queda así:

```nginx
    location /api/ {
        proxy_pass http://127.0.0.1:8081;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Remote-User     $remote_user;   # ← quién es el técnico
        client_max_body_size 25m;                          # ← sin esto, las fotos dan 413
        proxy_read_timeout   120s;                         # ← subidas con señal mala
    }
```

Las **dos líneas marcadas son nuevas y obligatorias**:

- Sin `client_max_body_size`, nginx corta la subida en 1 MB y el técnico ve *"la foto pesa
  demasiado"* aunque no lo pese. (El formulario ya reduce cada foto a ~1600 px / 300-400 kB
  antes de subirla; el margen es para ráfagas de varias fotos.)
- Sin `X-Remote-User`, el backend no sabe quién envió cada acta: el nombre no se precarga y —más
  serio— **cualquier usuario autenticado podría mandar la cabecera a mano y hacerse pasar por
  `leo` para borrar actas**. Al fijarla en nginx, el valor del cliente se sobrescribe siempre.
  Revisa si ya la tienes: es fácil que no, porque no venía en el README original.

```bash
sudo nginx -t && sudo systemctl reload nginx
```

### 5 · Usuarios de los técnicos (una sola vez)

```bash
sudo htpasswd /etc/nginx/hbox-docs.htpasswd alan
sudo htpasswd /etc/nginx/hbox-docs.htpasswd daniel
# (sin -c: -c CREA el archivo de cero y borraría a leo y a luz)
sudo cut -d: -f1 /etc/nginx/hbox-docs.htpasswd     # lista de usuarios
```

Administradores (quién puede borrar o reabrir actas) = variable `ACTAS_ADMINS` del servicio,
hoy `leo`. Alan y Daniel quedan como técnicos: llenan y envían, no borran.

### 7 · Permisos para que los técnicos cambien su contraseña (una sola vez)

La página **Mi cuenta** (`/cuenta.html`) deja que cada quien cambie su propia contraseña, y que el
administrador restablezca la de otro. Para eso el servicio tiene que poder **escribir** el archivo de
usuarios que nginx solo **lee**:

```bash
# quién es el usuario de nginx (normalmente www-data)
grep -E "^\s*user" /etc/nginx/nginx.conf

sudo chown leo:www-data /etc/nginx/hbox-docs.htpasswd
sudo chmod 640          /etc/nginx/hbox-docs.htpasswd
sudo systemctl restart actas-hbox
```

Así: **leo** (el servicio) escribe, **www-data** (nginx) lee, y nadie más puede ni leerlo.

Comprueba que las contraseñas estén en el formato que el servicio sabe verificar:

```bash
sudo cut -d: -f2 /etc/nginx/hbox-docs.htpasswd | cut -c1-6
```

Todas deben decir `$apr1$`. Si alguna sale distinta (`$2y$` es bcrypt), esa persona no va a poder
cambiar la suya sola: restablécesela desde la propia página, que la vuelve a guardar en `$apr1$`.

!!! note "Por qué no se usa el comando `htpasswd` desde el servicio"
    Pasar una contraseña como argumento (`htpasswd -b … clave`) la deja visible en `ps` para
    cualquiera con sesión en el servidor. El hash `$apr1$` se calcula dentro del proceso; está
    verificado carácter por carácter contra la salida de `htpasswd`, incluyendo acentos y espacios.

!!! tip "Al cambiar la contraseña, la sesión no se cae"
    HTTP Basic se guarda en el navegador: quien cambie la suya sigue navegando con la anterior hasta
    que cierre sesión o cierre el navegador. La página lo explica y ofrece la liga de **Salir** para
    probarla de inmediato. No es un error.

---

## B · Verificación después de desplegar

```bash
# 1. el backend responde y sabe quién eres
curl -s -u leo:PASS   https://drogheda.helgen.online/api/whoami   # {"user":"leo","admin":true}
curl -s -u alan:PASS  https://drogheda.helgen.online/api/whoami   # {"user":"alan","admin":false}
```

Si `user` sale vacío, falta la línea `X-Remote-User` del paso 4.

```bash
# 2. la subida de fotos funciona de punta a punta
curl -s -u alan:PASS -F tipo=diagnostico-campo -F serie=CAMPO-PRUEBA \
     -F foto=@cualquier-foto.jpg \
     https://drogheda.helgen.online/api/adjuntos
# → {"ok":true,"fotos":[{"ruta":"diagnostico-campo/CAMPO-PRUEBA/2026…jpg",…}]}

# 3. el acta de campo NO se bloquea al segundo envío
curl -s -u alan:PASS https://drogheda.helgen.online/api/historial\?tipo=diagnostico-campo\&serie=CAMPO-PRUEBA
```

Y la prueba que de verdad cuenta, desde un teléfono:
abrir `https://drogheda.helgen.online/formularios/diagnostico.html`, elegir la unidad
**⚙ PRUEBA (no cuenta)**, tomar una foto y enviar. Las series con `PRUEBA` se guardan aparte,
en `_pruebas/`, y no ensucian el registro.

---

## C · Ciclo normal a partir de aquí

```bash
# contenido nuevo desde el repo Drogheda (lista curada dentro del script)
./scripts/sync-docs.sh
git add -A && git commit -m "…" && git push
./scripts/deploy.sh
# y SOLO si tocaste backend/app.py:
ssh leo@git.helgen.online 'cd /srv/projects/drogheda/hbox-docs && git pull && sudo systemctl restart actas-hbox'
```

## D · Respaldo

Todo lo que los técnicos generan son dos carpetas planas — cópialas y ya:

```bash
rsync -az leo@git.helgen.online:/srv/projects/drogheda/actas/    ~/respaldo-actas/
rsync -az leo@git.helgen.online:/srv/projects/drogheda/adjuntos/ ~/respaldo-fotos/
```

## E · Problemas frecuentes

| Síntoma | Causa | Arreglo |
|---|---|---|
| *"La foto pesa demasiado"* con fotos normales | falta `client_max_body_size` | paso 4 |
| El nombre del técnico no se precarga | falta `X-Remote-User` | paso 4 |
| *"Ya existe un acta para esta serie"* en diagnóstico | backend viejo | paso 2 (`git pull` + restart) |
| Las fotos se ven rotas en el tablero | falta la carpeta `adjuntos` o su permiso | paso 3 |
| `mkdocs build --strict` falla | un enlace del `nav` apunta a un archivo que no existe | revisa `mkdocs.yml` |
| El técnico no puede entrar | usuario no creado, o se usó `htpasswd -c` y borró a los demás | paso 5 |
| «El servicio no tiene permiso de escribir el archivo de usuarios» | falta el `chown`/`chmod` del htpasswd | paso 7 |
| «Tu contraseña está guardada en un formato que no puedo verificar» | esa entrada es bcrypt, no `$apr1$` | restablecerla desde `/cuenta.html` como administrador |