txoko-dashboard/SETUP.md

# Cómo subir Txoko a Gitea — paso a paso

Instrucciones exactas. Copiar y pegar en la terminal del Mac.
No hace falta entender git para seguir esto.

---

## PASO 1 — Crear el repo en Gitea (una sola vez)

1. Abre tu instancia de Gitea en el navegador
2. Clic en el **+** (arriba a la derecha) → "New Repository"
3. Rellena:
   - **Repository Name:** `txoko-dashboard`
   - **Description:** `Suite de auditoría de privacidad Bitcoin para nodos propios`
   - **Visibility:** Private (o Public si quieres compartirlo con la comunidad)
   - **Initialize repository:** NO marcar (ya traemos nuestros archivos)
4. Clic en "Create Repository"
5. Gitea te muestra una página con instrucciones — copia la URL del repo,
   será algo como: `https://gitea.tu-comunidad/tu-usuario/txoko-dashboard.git`

---

## PASO 2 — Configurar git en el Mac (una sola vez, si no lo tienes)

```bash
git config --global user.name "tu nombre"
git config --global user.email "tu@email.com"
```

Comprueba que git está instalado:
```bash
git --version
```
Si no está: `brew install git`

---

## PASO 3 — Crear el repo local y primer commit (una sola vez)

```bash
# Crear carpeta del proyecto en el Mac
mkdir ~/txoko-dashboard
cd ~/txoko-dashboard

# Copiar los archivos del repo que te he preparado
# (descarga los archivos de esta conversación y cópialos aquí)

# Inicializar git
git init
git branch -M main

# Añadir todos los archivos
git add .

# Primer commit — el historial empieza aquí
git commit -m "inicio: dashboard de privacidad Bitcoin con análisis on-chain"
```

---

## PASO 4 — Conectar con Gitea y subir (una sola vez)

```bash
# Sustituye la URL por la de tu repo de Gitea
git remote add origin https://gitea.tu-comunidad/tu-usuario/txoko-dashboard.git

# Subir
git push -u origin main
```

Gitea te pedirá usuario y contraseña la primera vez.
Si quieres evitar introducirlos cada vez, crea un token en
Gitea → Settings → Applications → "Generate Token" y úsalo como contraseña.

---

## PASO 5 — Flujo de trabajo normal (cada vez que yo te dé un archivo nuevo)

```bash
cd ~/txoko-dashboard

# Copiar el archivo actualizado descargado de esta conversación
cp ~/Downloads/txoko-dashboard.html ./dashboard.html

# Ver qué cambió (opcional pero útil)
git diff dashboard.html

# Registrar el cambio con un mensaje descriptivo
git add dashboard.html
git commit -m "fix: descripción breve de lo que se arregló"

# Subir a Gitea
git push

# Copiar al nodo (igual que antes)
scp dashboard.html armg@100.116.19.86:/home/armg/txoko/dashboard.html
```

---

## Mensajes de commit — ejemplos

El mensaje va después de `-m` y describe QUÉ cambiaste.
No tiene que ser perfecto, solo útil para ti en el futuro.

```
"fix: timeout en consultas al nodo"
"feat: score por bandas ALTA/MEDIA/BAJA"
"fix: responsive pestaña Mempool en móvil"
"fix: detección Whirlpool con tolerancia 2%"
"feat: fingerprinting wallet completo"
"fix: umbral dust por tipo de salida"
"docs: actualizar README con nuevas funcionalidades"
```

Convención (opcional pero ordenada):
- `fix:` — corrige algo que no funcionaba bien
- `feat:` — añade algo nuevo
- `docs:` — solo documentación

---

## Si algo sale mal

**Subiste algo que no querías:**
```bash
git revert HEAD
git push
```

**Quieres volver a una versión anterior:**
```bash
git log --oneline          # ver el historial
git checkout HASH_DEL_COMMIT -- dashboard.html   # recuperar ese archivo
```

**Ver el historial:**
```bash
git log --oneline
```

---

## Resumen del flujo

```
Claude te da dashboard.html
       ↓
cp ~/Downloads/dashboard.html ./dashboard.html
       ↓
git add . && git commit -m "descripción"
       ↓
git push
       ↓
scp dashboard.html armg@100.116.19.86:/home/armg/txoko/
```

Cuatro comandos después de la descarga. Siempre los mismos.

---

## Librerías del frontend (obligatorio)

El dashboard usa React y Babel. **Se sirven desde tu propio nodo, no desde un
CDN.** El motivo es de privacidad, no de comodidad: un CDN externo no ve qué
transacciones analizas, pero sí ve que usas Txoko, cuándo y desde qué IP
pública — exactamente la clase de metadato que esta herramienta enseña a
proteger. Sirviéndolas en local, *"ninguna consulta sale de tu red"* pasa a ser
literal, y el dashboard funciona sin conexión a internet.

Estas librerías **no están en el repo** (son de terceros y pesan ~3 MB). Se
descargan una vez, en el nodo:

```bash
sudo mkdir -p /usr/share/nginx/html/vendor
cd /usr/share/nginx/html/vendor
sudo curl -sSLO https://unpkg.com/react@18.3.1/umd/react.production.min.js
sudo curl -sSLO https://unpkg.com/react-dom@18.3.1/umd/react-dom.production.min.js
sudo curl -sSL -o babel.min.js https://unpkg.com/@babel/standalone@7.23.10/babel.min.js
```

### Verifica lo que has descargado

No te fíes: comprueba que los archivos son los que deben ser.

```bash
sha256sum *.js
```

Debe dar exactamente esto:

```
85ba0c7207cf1b1850e40372f26a7e69a481457a29649b7ca19bbfce8604f30c  babel.min.js
35f4f974f4b2bcd44da73963347f8952e341f83909e4498227d4e26b98f66f0d  react-dom.production.min.js
d949f1c3687aedadcedac85261865f29b17cd273997e7f6b2bfc53b2f9d4c4dd  react.production.min.js
```

Si algún hash no coincide, **no uses esos archivos**: significa que has
recibido algo distinto a lo esperado.

Las versiones están fijadas a propósito (`18.3.1`, `7.23.10`). Usar un rango
como `react@18` dejaría que el servidor decidiera qué versión te entrega, y
cambiaría con el tiempo sin que te enteres.

### Dónde deben quedar los archivos

El dashboard las busca en `vendor/` con **ruta relativa**, es decir, en un
subdirectorio junto al propio `dashboard.html`. Así funciona tanto si sirves el
dashboard en la raíz como bajo un prefijo, sin tocar nginx.

Con la configuración típica de Mempool self-hosted:

```nginx
location /dashboard {
    alias /usr/share/nginx/html/;
}
```

…el `dashboard.html` vive en `/usr/share/nginx/html/` y las librerías deben ir
en `/usr/share/nginx/html/vendor/` — que es justo donde las deja el comando de
arriba.

**Importante:** abre el dashboard **con la barra final** (`.../dashboard/`, no
`.../dashboard`). Sin ella, el navegador resuelve las rutas relativas un nivel
por encima y no encuentra las librerías.

Para comprobar que nginx las sirve bien, lo que importa no es solo el código
200 sino el tipo de contenido:

```bash
curl -sk -o /dev/null -w '%{http_code} %{content_type}\n' \
  https://localhost:4081/dashboard/vendor/react.production.min.js
```

Debe responder `200 application/javascript`. Si devuelve `200 text/html`,
nginx está entregando otra cosa (por ejemplo el index de Mempool) y las rutas
no son las correctas.

---

## HTTPS para watch-only (opcional)

La función watch-only (derivar tus direcciones desde el xpub) usa la Web Crypto
API del navegador, que **solo funciona sobre HTTPS**. Si sirves el dashboard por
HTTP, watch-only no estará disponible — el resto de la app funciona igual. Las
etiquetas BIP-329 no necesitan HTTPS.

Si quieres usar watch-only y tu nodo va por HTTP (por ejemplo, acceso por
Tailscale sin certificado), puedes generar un certificado autofirmado. Es lo que
sigue. Todo se hace en el nodo.

### 1. Generar el certificado autofirmado

Sustituye la IP por la de tu nodo (Tailscale, local, etc.):

```bash
sudo openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
  -keyout /etc/ssl/private/txoko.key \
  -out /etc/ssl/certs/txoko.crt \
  -subj "/CN=100.116.19.86" \
  -addext "subjectAltName=IP:100.116.19.86"
```

### 2. Configurar nginx para servir HTTPS

Añade un bloque `server` que escuche en un puerto con SSL (por ejemplo 4081),
apuntando al certificado recién creado e incluyendo la misma configuración que
tu servidor HTTP:

```nginx
server {
    listen 4081 ssl;
    listen [::]:4081 ssl;
    server_name _;
    ssl_certificate /etc/ssl/certs/txoko.crt;
    ssl_certificate_key /etc/ssl/private/txoko.key;
    ssl_session_timeout 4h;
    ssl_protocols TLSv1.3;
    ssl_prefer_server_ciphers on;

    # Incluye aquí tu misma config (location /dashboard, /api/, etc.)
    # Si ya tienes esos location en un snippet, basta con incluirlo:
    # include /etc/nginx/snippets/tu-config.conf;
}
```

Si el bloque `location /dashboard` ya viene de un snippet que incluyes, **no lo
dupliques** dentro del server SSL: nginx dará error `duplicate location`.

Comprueba y recarga:

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

### 3. Confiar el certificado la primera vez

Abre `https://TU-IP:4081/dashboard/` en el navegador. Como el certificado es
autofirmado, el navegador avisará de que la conexión no es privada. Es esperado
—lo creaste tú— y es seguro en tu propia red:

- **Safari:** clic en "visitar este sitio web" (abajo del aviso) y confirma
- **Chrome/Brave:** "Configuración avanzada" → "Acceder a TU-IP (no seguro)"

A partir de ahí el navegador recuerda la excepción y la Web Crypto API queda
disponible, así que watch-only funcionará.

> Nota: un certificado autofirmado es perfectamente válido para uso personal en
> tu propia red. El aviso del navegador existe porque no hay una autoridad
> certificadora de por medio, no porque la conexión sea insegura — el tráfico va
> cifrado igual.