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)

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

Comprueba que git está instalado:

git --version

Si no está: brew install git

---

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

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

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

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:

git revert HEAD
git push

Quieres volver a una versión anterior:

git log --oneline          # ver el historial
git checkout HASH_DEL_COMMIT -- dashboard.html   # recuperar ese archivo

Ver el historial:

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:

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.

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:

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:

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

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:

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:

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.