pikaro
d3caaf6186
SETUP.md no era una guía de instalación: más de la mitad eran los pasos personales de git y Gitea del autor. Se mueven a un documento privado. Y lo importante: la configuración de nginx documentada en el README estaba rota desde la 1.11.0. Indicaba un alias a dashboard.html (un ARCHIVO), pero con las librerías en vendor/ y rutas relativas eso deja al navegador sin encontrarlas — página en blanco y ningún error visible. Debe ser un alias al DIRECTORIO. Quien siguiera el README al pie de la letra no conseguía arrancar. Ahora hay una guía real con comprobación tras cada paso, incluida la que descarta ese fallo concreto: curl mirando el content-type, no solo el 200. Se añaden las librerías al flujo (faltaban, y sin ellas no arranca), se quitan las rutas personales y se actualiza la estructura del repo.
319 lines
9.9 KiB
Markdown
319 lines
9.9 KiB
Markdown
# 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" |
|