Leopoldo Rodríguez 7b8fb4f9d1 sitio: reorganización por tareas, búsqueda, estilo Helgen, todo en español, procedimientos KISS

2026-09-28 20:05:32 -06:00

8.4 KiB

Raw Blame History

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

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

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)

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):

Environment=ADJUNTOS_DIR=/srv/projects/drogheda/adjuntos
Environment=ADJUNTO_MAX_MB=8
Environment=ARCHIVO_MAX_MB=20
Environment=ACTAS_REPETIBLES=diagnostico-campo,diagnostico-banco,instalacion-campo,reflasheo,dano,envio,recepcion,prueba-bateria-modem,prueba-ethernet-serie

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í:

    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.

sudo nginx -t && sudo systemctl reload nginx

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

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:

# 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:

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

# 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.

# 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í

# 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:

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

8.4 KiB Raw Blame History