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.

---

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.