pikaro/txoko-dashboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: reescribir la guía de instalación, que llevaba a una app rota

Browse Source 
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.
This commit is contained in:
Aitor
2026-07-27 16:38:48 +02:00
parent b5db5d7e81
commit b579a0653a
5 changed files with 307 additions and 296 deletions
Download Patch File Download Diff File Expand all files Collapse all files
SETUP.md
+239 -233
View File
@@ -1,187 +1,93 @@
# Cómo subir Txoko a Gitea — paso a paso
# Instalación de Txoko Node Dashboard
Instrucciones exactas. Copiar y pegar en la terminal del Mac.
No hace falta entender git para seguir esto.
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.
---
## PASO 1 — Crear el repo en Gitea (una sola vez)
## Antes de empezar
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`
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) |
## PASO 2 — Configurar git en el Mac (una sola vez, si no lo tienes)
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
git config --global user.name "tu nombre"
git config --global user.email "tu@email.com"
curl -s http://127.0.0.1:8999/api/v1/fees/recommended
```
Comprueba que git está instalado:
```bash
git --version
```
Si no está: `brew install git`
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 3 — Crear el repo local y primer commit (una sola vez)
## Paso 1 — Descargar los archivos
```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"
git clone https://git.bitcointxoko.org/pikaro/txoko-dashboard.git
cd txoko-dashboard
```
---
## PASO 4 — Conectar con Gitea y subir (una sola vez)
## 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
# 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
sudo mkdir -p /var/www/txoko
sudo cp dashboard.html /var/www/txoko/
```
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.
Puedes usar otra ruta; solo recuerda cuál es, porque aparece en los pasos 3 y 5.
---
## PASO 5 — Flujo de trabajo normal (cada vez que yo te dé un archivo nuevo)
## 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
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 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
```
### Verifica lo que has descargado
No te fíes: comprueba que los archivos son los que deben ser.
**Comprueba que has recibido lo que esperabas.** No te fíes: verifícalo.
```bash
sha256sum *.js
@@ -195,118 +101,218 @@ Debe dar exactamente esto:
d949f1c3687aedadcedac85261865f29b17cd273997e7f6b2bfc53b2f9d4c4dd react.production.min.js
```
Si algún hash no coincide, **no uses esos archivos**: significa que has
recibido algo distinto a lo esperado.
Si alguno no coincide, **para aquí**: has recibido algo distinto de 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.
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.
### 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:
### Las fuentes
```bash
curl -sk -o /dev/null -w '%{http_code} %{content_type}\n' \
https://localhost:4081/dashboard/vendor/react.production.min.js
sudo /ruta/al/repo/instalar-fuentes.sh /var/www/txoko/vendor/fonts
```
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.
El script descarga IBM Plex (licencia libre OFL), comprueba cada archivo y
aborta si algo falla. Son unos 350 KB.
---
## HTTPS para watch-only (opcional)
## Paso 4 — El monitor del sistema (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.):
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
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"
mkdir -p ~/txoko
cp system-metrics.js ~/txoko/
```
### 2. Configurar nginx para servir HTTPS
Edita `~/txoko/system-metrics.js` y sustituye los dos marcadores por tus
credenciales RPC de Bitcoin Core (las de tu `bitcoin.conf`):
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:
```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
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;
# 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;
}
# 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;
# 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;
}
```
Si el bloque `location /dashboard` ya viene de un snippet que incluyes, **no lo
dupliques** dentro del server SSL: nginx dará error `duplicate location`.
**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.
Comprueba y recarga:
Recarga nginx:
```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:
## Paso 6 — Comprobar que funciona
- **Safari:** clic en "visitar este sitio web" (abajo del aviso) y confirma
- **Chrome/Brave:** "Configuración avanzada" → "Acceder a TU-IP (no seguro)"
Antes de abrir el navegador, verifica desde el propio nodo. Ajusta el puerto:
A partir de ahí el navegador recuerda la excepción y la Web Crypto API queda
disponible, así que watch-only funcionará.
```bash
# El dashboard llega
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:4080/dashboard/
> 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.
# 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" |