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)	la API que Txoko consulta
Fulcrum (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:

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

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.

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

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.

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

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.

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

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:

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

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

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

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:

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

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:

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

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"