txoko-dashboard/SETUP.md

# Instalación de Txoko Node Dashboard

Guía completa, de principio a fin. Sigue los pasos en orden y comprueba cada
uno antes de pasar al siguiente: cada comprobación te dice si vas bien, en vez
de dejarte descubrirlo al final con una pantalla en blanco.

Todo se hace **en el nodo**, salvo donde se indique lo contrario.

---

## Antes de empezar

Txoko no habla con la red Bitcoin directamente: se apoya en cosas que ya
tienes montadas. Necesitas:

| Requisito | Para qué |
|---|---|
| **Bitcoin Core** con `txindex=1` | consultar cualquier transacción, no solo las tuyas |
| **Mempool self-hosted** ([mempool/mempool](https://github.com/mempool/mempool)) | la API que Txoko consulta |
| **Fulcrum** ([cculianu/Fulcrum](https://github.com/cculianu/Fulcrum)) | índice de direcciones; Mempool lo usa por debajo |
| **nginx** | sirve el dashboard y hace de proxy hacia lo anterior |
| **Node.js ≥ 18** | solo para el monitor del sistema (paso 4) |

Si Mempool self-hosted ya te funciona en el navegador, tienes todo lo demás.

Comprueba que la API responde antes de seguir. Ajusta el puerto al tuyo:

```bash
curl -s http://127.0.0.1:8999/api/v1/fees/recommended
```

Debe devolver un JSON con comisiones. Si no responde, arregla eso primero:
Txoko no puede funcionar sin ello.

> **Nunca expongas estos puertos a internet.** Txoko está pensado para
> accederse por Tailscale, VPN o red local.

---

## Paso 1 — Descargar los archivos

```bash
git clone https://git.bitcointxoko.org/pikaro/txoko-dashboard.git
cd txoko-dashboard
```

---

## Paso 2 — Elegir dónde vivirá el dashboard

Esta decisión condiciona el resto, así que conviene hacerla a conciencia.

Necesitas un **directorio** propio para Txoko. No vale colocar el
`dashboard.html` suelto en cualquier sitio: la aplicación carga sus librerías
desde un subdirectorio `vendor/` **junto al propio archivo**, así que ambos
tienen que convivir.

```bash
sudo mkdir -p /var/www/txoko
sudo cp dashboard.html /var/www/txoko/
```

Puedes usar otra ruta; solo recuerda cuál es, porque aparece en los pasos 3 y 5.

---

## Paso 3 — Instalar las librerías del frontend

Txoko usa React y Babel, y la tipografía IBM Plex. **Se sirven desde tu propio
nodo, nunca desde un CDN externo.**

El motivo es de privacidad, no de comodidad: un CDN no vería qué transacciones
analizas, pero sí recibiría tu IP y la hora cada vez que abres el dashboard —
sabría que usas Txoko, cuándo y desde dónde. Justo el metadato que esta
herramienta enseña a proteger. Sirviéndolas en local, *"ninguna consulta sale
de tu red"* es literal, y el dashboard funciona sin conexión a internet.

No están en el repositorio porque son código de terceros y ocupan unos 3 MB.

### React y Babel

```bash
sudo mkdir -p /var/www/txoko/vendor
cd /var/www/txoko/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
```

**Comprueba que has recibido lo que esperabas.** No te fíes: verifícalo.

```bash
sha256sum *.js
```

Debe dar exactamente esto:

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

Si alguno no coincide, **para aquí**: has recibido algo distinto de lo esperado.

Las versiones están fijadas a propósito. 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.

### Las fuentes

```bash
sudo /ruta/al/repo/instalar-fuentes.sh /var/www/txoko/vendor/fonts
```

El script descarga IBM Plex (licencia libre OFL), comprueba cada archivo y
aborta si algo falla. Son unos 350 KB.

---

## Paso 4 — El monitor del sistema (opcional)

Alimenta la pestaña NODO: CPU, RAM, disco, estado de Bitcoin Core y logs. Sin
esto el resto de la aplicación funciona igual, solo que esa pestaña queda vacía.

```bash
mkdir -p ~/txoko
cp system-metrics.js ~/txoko/
```

Edita `~/txoko/system-metrics.js` y sustituye los dos marcadores por tus
credenciales RPC de Bitcoin Core (las de tu `bitcoin.conf`):

```js
const RPC_USER = "TU_RPC_USER";
const RPC_PASS = "TU_RPC_PASSWORD";
```

Instala el servicio. Antes revisa el `.service`, porque trae rutas y usuario
que probablemente tengas que ajustar a los tuyos:

```bash
nano txoko-metrics.service
sudo cp txoko-metrics.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now txoko-metrics
```

**Comprueba que arrancó:**

```bash
systemctl is-active txoko-metrics     # debe decir: active
curl -s http://127.0.0.1:4082/system/info | head -c 200
```

> Si `systemctl status` muestra un punto que no es verde pero pone
> `active (running)`, está bien. Lo que importa es el texto.

---

## Paso 5 — Configurar nginx

Aquí es donde más gente se atasca, así que léelo con calma.

Añade esto a tu configuración de nginx (si usas Mempool self-hosted, dentro del
mismo bloque `server`):

```nginx
# Dashboard — OJO: alias a un DIRECTORIO, con barra final
location /dashboard/ {
    alias /var/www/txoko/;
    index dashboard.html;
    try_files $uri $uri/ /dashboard/dashboard.html;
}

# API de Mempool — ajusta el puerto al de tu instalación
location /api/ {
    proxy_pass http://127.0.0.1:8999;
}

# Monitor del sistema (solo si hiciste el paso 4)
location /system/ {
    proxy_pass http://127.0.0.1:4082;
}
```

**El detalle que rompe la instalación:** el `alias` tiene que apuntar al
**directorio**, con barra final, no al archivo `dashboard.html`. Si apunta al
archivo, el navegador no encontrará `vendor/` y verás una **página en blanco**
sin ningún mensaje de error. Es el fallo más común de esta instalación.

Recarga nginx:

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

---

## Paso 6 — Comprobar que funciona

Antes de abrir el navegador, verifica desde el propio nodo. Ajusta el puerto:

```bash
# El dashboard llega
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:4080/dashboard/

# Y las librerías TAMBIÉN — esto es lo que suele fallar
curl -s -o /dev/null -w '%{http_code} %{content_type}\n' \
  http://127.0.0.1:4080/dashboard/vendor/react.production.min.js
```

La segunda debe responder **`200 application/javascript`**.

Si devuelve `200 text/html` la instalación **no** está bien: nginx te está
sirviendo otra cosa (normalmente el index de Mempool) en lugar del archivo.
Revisa el `alias` del paso 5. Fíjate en que aquí no basta con mirar el código
200 — hay que mirar el tipo de contenido.

Ahora sí, abre en el navegador:

```
http://TU-IP:4080/dashboard/
```

**Con la barra final.** Sin ella, el navegador busca las librerías un nivel por
encima y no las encuentra.

Pulsa **CONFIG** e introduce la URL de tu Mempool (por ejemplo
`http://TU-IP:4080`). Dale a PROBAR: si dice "Conexión exitosa", ya está.

### Si ves una página en blanco

Abre la consola del navegador (F12). Si aparece `SyntaxError: Unexpected
token '<'`, es exactamente el problema del `alias` del paso 5: nginx está
devolviendo HTML donde debería devolver JavaScript.

---

## HTTPS — necesario para el 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**. Por HTTP el resto de la
aplicación funciona igual; solo esa función queda deshabilitada. Las etiquetas
BIP-329 no necesitan HTTPS.

Si accedes por Tailscale o red local no tendrás un certificado válido, así que
toca generar uno autofirmado.

### 1. Generar el certificado

Sustituye la IP por la de tu nodo:

```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.64.0.5" \
  -addext "subjectAltName=IP:100.64.0.5"
```

El `subjectAltName` no es opcional: sin él los navegadores modernos rechazan el
certificado aunque el `CN` sea correcto.

### 2. Servirlo en nginx

Duplica tu bloque `server` en otro puerto (4081 en este ejemplo) añadiendo:

```nginx
listen 4081 ssl;
ssl_certificate     /etc/ssl/certs/txoko.crt;
ssl_certificate_key /etc/ssl/private/txoko.key;
```

Los `location` son los mismos del paso 5. Recarga con `sudo nginx -t &&
sudo systemctl reload nginx`.

### 3. Aceptar el certificado la primera vez

Al entrar en `https://TU-IP:4081/dashboard/` el navegador avisará de que el
certificado no es de confianza. Es lo esperado: lo has firmado tú. Acepta la
excepción una vez.

Que sea autofirmado no lo hace menos seguro **para este uso**: cifra igual, y
como el certificado lo has generado tú en tu propia máquina, nadie externo
puede suplantarlo. Lo que no tienes es el respaldo de una autoridad
certificadora, que aquí no aporta nada porque el servidor y el cliente son
tuyos.

---

## Actualizar a una versión nueva

```bash
git pull
sudo cp dashboard.html /var/www/txoko/
```

Y recarga el navegador con **Ctrl+Shift+R** (o Cmd+Shift+R en Mac) para saltarte
la caché.

Las librerías de `vendor/` no hace falta volver a descargarlas salvo que el
CHANGELOG diga lo contrario. Si además cambia `system-metrics.js`, cópialo de
nuevo (conservando tus credenciales) y reinicia con
`sudo systemctl restart txoko-metrics`.

---

## Problemas frecuentes

| Síntoma | Causa habitual |
|---|---|
| Página en blanco, consola con `Unexpected token '<'` | El `alias` de nginx apunta al archivo y no al directorio (paso 5) |
| Página en blanco al entrar sin barra final | Entra en `/dashboard/`, con barra |
| Aparece "DEMO · SIN NODO" | Falta configurar la URL del Mempool en CONFIG |
| La pestaña NODO está vacía | El servicio `txoko-metrics` no corre, o falta el `location /system/` |
| Watch-only no aparece | Estás entrando por HTTP; requiere HTTPS |
| La app dice que el nodo no responde | Comprueba la API con el `curl` de "Antes de empezar" |