De ThunderHub v0.15.x a v0.18.0 con base de datos para notas permanentes en canales: la guía que me ha servido
- Pre-requisitos
- Setup único (solo la primera vez)
- Procedimiento de actualización
- 1. Parar el servicio
- 2. Cambiar al usuario thunderhub
- 3. Definir la versión objetivo
- 4. Descartar cambios locales auto-generados
- 5. Fetch del tag (sin merge todavía)
- 6. Verificar la firma GPG
- 7. Mergear
- 8. Leer el changelog antes de instalar
- 9. Limpiar el build anterior — OBLIGATORIO en este salto
- 10. Instalar dependencias y construir
- 11. Verificar la versión
- 12. Configurar el .env.local
- 13. Salir y arrancar el servicio
- 14. Verificaciones críticas en el log
- Setup inicial post-upgrade
- Por qué DB_ENCRYPTION_KEY merece una sección entera
- Cómo usar la feature de notas por canal
- Solución de problemas
- “Error: GetWalletInfoErr … self-signed certificate” en bucle cada 60 segundos
- Pantalla “Welcome to ThunderHub” cuando deberías ver la lista de cuentas
- “Your local changes to the following files would be overwritten by merge”
- “gpg: Can’t check signature: No public key” con clave B5690EEEBB952194
- “sh: 1: rimraf: not found” durante npm run build
- El servicio arranca pero isProduction: false en el log
- Postgres rechaza la conexión: “FATAL: Peer authentication failed”
- Si todo lo demás falla
- Procedimiento resumido (chuleta)
- Por qué esto importa
Si llegas con un nodo Lightning instalado siguiendo minibolt y ThunderHub corriendo en algún punto de la rama 0.15.x, este salto a v0.18.0 no es una actualización más. ThunderHub ha cambiado dos veces de paradigma por el camino: en v0.15 migró de Next.js a Vite + React Router (cambios fuertes en frontend), y en v0.16 introdujo una capa de base de datos opcional para gestionar usuarios y nodos. Para la rama 0.18 esa capa de base de datos no es solo una opción más bonita: es el único camino si quieres aprovechar las features nuevas, en particular la persistencia de notas por canal (channel_metadata).
Esta guía cubre el upgrade entero, desde el setup único de claves GPG y el endurecimiento del JWT secret, hasta la creación del Postgres, el primer login con email/password, y la conexión del nodo LND a través de la nueva UI. Lo hago con un trampa importante destacada al final: la variable DB_ENCRYPTION_KEY, que no aparece en el .env de ejemplo y sin la cual ThunderHub guarda tu macaroon en plano y luego falla al conectarse a LND con un críptico self-signed certificate. Si saltas ese punto, te van a pasar cosas raras durante horas.
Sirve para minibolt sobre Ubuntu 22.04 / 24.04 con paths estándar (/data/lnd/...). Si tu setup es distinto, ajusta paths.
Pre-requisitos
Antes de empezar, comprueba que tienes:
Node.js 24.x. Desde v0.15.0 ThunderHub requiere Node 24 como mínimo. Para verificar:
node --version
Si te devuelve v20.x o v22.x (lo que minibolt instalaba en su día con la rama 0.14), tienes que actualizar Node antes de tocar ThunderHub. La forma limpia en minibolt es seguir la propia guía de actualización de Node (paquete nodejs desde el repo de NodeSource), pero eso queda fuera del alcance de este post.
PostgreSQL instalado y corriendo. En minibolt suele estar ya presente porque otros servicios lo usan. Verifica:
sudo systemctl status postgresql
psql --version
Si no está, en Ubuntu 22.04+:
sudo apt update && sudo apt install -y postgresql postgresql-contrib
sudo systemctl enable --now postgresql
El usuario thunderhub y su directorio de trabajo ya existen porque tu nodo viene corriendo desde 0.15.x. Si por alguna razón no fuera así, esta guía no es la tuya — necesitas la guía de instalación inicial de minibolt antes.
Backup mental de lo que tienes ahora: el fichero thubConfig.yaml con tu masterPassword y la cuenta YAML, que vamos a retirar. Anota la password real (no el hash bcrypt) por si en algún momento quieres volver a YAML como fallback.
Setup único (solo la primera vez)
Esto se hace una sola vez en la vida de tu nodo. Si ya lo hiciste en una actualización anterior, salta.
1. Importar las claves GPG
ThunderHub firma sus releases con dos claves distintas: la personal del mantenedor y la de GitHub para releases vía bot. Necesitas las dos importadas en el keyring del usuario thunderhub. Si solo importas una, en algún update futuro vas a ver Can't check signature: No public key y te quedarás bloqueado.
Como admin:
sudo su - thunderhub
# Clave personal de apotdevin (mantenedor)
gpg --keyserver hkps://keys.openpgp.org --recv-keys 4403F1DFBE779457
# Si el primer keyserver falla, prueba con:
# gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys 4403F1DFBE779457
# Clave de GitHub web-flow (no está en keyservers públicos)
curl https://github.com/web-flow.gpg | gpg --import
exit
¿Por qué dos? Porque ThunderHub mezcla commits firmados por el mantenedor en local (clave 4403F1DFBE779457) con releases generados por la GitHub Action release-please, que se firman con la clave web-flow (B5690EEEBB952194). Las dos firmas son legítimas; solo cambia el origen.
2. Activar NODE_ENV=production con override de systemd
Por defecto, el servicio thunderhub.service arranca sin NODE_ENV=production definido. Esto tiene una consecuencia poco evidente: el código usa el JWT secret hardcodeado '123456789' en lugar de generar uno fuerte. Cualquiera con acceso a tu red local podría forjar tokens de sesión válidos sin saber tu contraseña.
Como admin:
sudo mkdir -p /etc/systemd/system/thunderhub.service.d/
sudo tee /etc/systemd/system/thunderhub.service.d/override.conf > /dev/null <<'EOF'
[Service]
Environment="NODE_ENV=production"
EOF
sudo systemctl daemon-reload
A partir de aquí, cada arranque de ThunderHub generará un JWT secret aleatorio fortísimo (128 hex). El único efecto visible: cuando reinicies el servicio se invalidan las sesiones activas y tendrás que volver a hacer login. Para uso personal, totalmente aceptable.
3. Crear la base de datos en PostgreSQL
ThunderHub no crea ni la BD ni el usuario por sí solo: hay que dárselos hechos. Como admin:
# Genera una password fuerte de 64 hex y guárdatela aparte
DBPASS=$(openssl rand -hex 32)
echo "DB password (cópiala a sitio seguro AHORA): $DBPASS"
sudo -u postgres psql <<EOF
CREATE USER thunderhub WITH PASSWORD '$DBPASS';
CREATE DATABASE thunderhub OWNER thunderhub;
EOF
Verifica que puedes conectarte como thunderhub:
psql "postgresql://thunderhub:$DBPASS@127.0.0.1:5432/thunderhub" -c "\conninfo"
Debe responder You are connected to database "thunderhub".... Si te dice connection refused o autenticación fallida, revisa que PostgreSQL escucha en 127.0.0.1:5432 y que el pg_hba.conf permite conexiones por contraseña a localhost (suele ser el default en Ubuntu, pero en algunos minibolt está configurado solo por socket peer auth, lo cual también funciona con un detalle adicional — si te falla, la solución es añadir 127.0.0.1/32 md5 en pg_hba.conf y reload).
4. Generar la clave de cifrado de la BD
Esta variable es crítica y le dedico una sección entera más abajo. De momento, solo genera el valor:
echo "DB_ENCRYPTION_KEY (también cópiala a sitio seguro): $(openssl rand -hex 32)"
Guarda este valor junto con la password del Postgres. Lo necesitarás en el siguiente paso. Esta clave no se puede regenerar sin perder los nodos guardados — si la pierdes, todos los macaroons cifrados en la BD quedan irrecuperables.
Procedimiento de actualización
Estos pasos se ejecutan en orden cada vez que actualices, pero el primero es el más cargado porque es el salto desde una rama vieja.
1. Parar el servicio
Como admin:
sudo systemctl stop thunderhub
2. Cambiar al usuario thunderhub
sudo su - thunderhub
cd thunderhub
A partir de aquí, todo lo que indique “como thunderhub” se ejecuta en esta shell. Si en algún punto necesitas hacer algo con privilegios (systemctl, edición de fichero del sistema), tienes que exit para volver a la shell de admin. El usuario thunderhub no está en sudoers por diseño — no intentes meterle sudo por delante.
3. Definir la versión objetivo
VERSION=0.18.0 # ajusta a la última disponible cuando leas esto
Mira siempre antes los releases en github.com/apotdevin/thunderhub/releases y lee el changelog. Para v0.17.x y v0.18.x hay cambios significativos que conviene conocer.
4. Descartar cambios locales auto-generados
Tras cada npm install o npm run build, ThunderHub modifica algunos ficheros que entran en conflicto al hacer git pull. Los descartamos limpiamente:
git checkout -- package-lock.json schema.gql 2>/dev/null
5. Fetch del tag (sin merge todavía)
git fetch https://github.com/apotdevin/thunderhub.git tag v$VERSION
6. Verificar la firma GPG
Esto es la diferencia más importante con la guía oficial. No mergees a ciegas.
git verify-commit v$VERSION^{commit}
Lo que debe aparecer es alguna de estas dos cosas:
gpg: Good signature from "Anthony Potdevin <potdevin.anthony@gmail.com>"
O alternativamente:
gpg: Good signature from "GitHub <noreply@github.com>"
Cualquiera de las dos es válida — depende de cómo se haya generado el commit del tag (manual del mantenedor, vs automático por la GitHub Action de release). Si aparece Can't check signature: No public key con una clave que no reconoces, o BAD signature, PARA y averigua antes de continuar. No es paranoia: es la única forma de detectar un compromiso del repositorio.
El warning This key is not certified with a trusted signature es cosmético y se puede ignorar — significa solo que no has marcado las claves como confiables localmente con tu propia clave GPG.
7. Mergear
git merge v$VERSION
8. Leer el changelog antes de instalar
less CHANGELOG.md
En este salto particular (0.15.x → 0.18.x) hay tres bloques de cambios importantes:
- v0.15.0: migración de Next.js a Vite + React Router, requiere Node 24, cambio del bundler frontend.
- v0.16.0: introducción del soporte de base de datos (
db initial setup,node tables,add db nodes and switch in ui), bake super macaroon, integración Magma in-app. - v0.17.x y v0.18.x: la feature de
channel_metadata(notas persistentes por canal), filtrado de Magma orders por nodo, mejoras en flujo de Taproot Assets, fixes varios.
Apunta cualquier variable de entorno nueva que veas mencionada. En este salto, las que importan son DB_TYPE, DB_POSTGRES_URL, DB_ENCRYPTION_KEY (esta no está en el .env de ejemplo, ojo), y opcionalmente DB_SQLITE_PATH si usaras SQLite en lugar de Postgres.
9. Limpiar el build anterior — OBLIGATORIO en este salto
Para un salto patch dentro de la misma minor (0.16.1 → 0.16.2) no hace falta. Para uno minor (0.16.x → 0.17.x) es recomendable. Para un salto de dos minors o más como el nuestro (0.15.x → 0.18.x) es obligatorio:
rm -rf node_modules dist src/client/dist
npm cache clean --force
Sin esto, te vas a comer errores tipo rimraf: not found, Cannot find module 'X', o builds rotos que solo se manifiestan en runtime.
10. Instalar dependencias y construir
npm install
Si te corta con ECONNRESET (típico en redes detrás de Tor o con conexiones inestables), aumenta los timeouts y reintenta:
npm config set fetch-retries 5
npm config set fetch-retry-mintimeout 20000
npm config set fetch-retry-maxtimeout 120000
npm config set fetch-timeout 600000
rm -rf node_modules
npm install
Los warnings de deprecated, ERESOLVE y npm audit son ruido del ecosistema npm — son responsabilidad del mantenedor, no tuya. No ejecutes npm audit fix, puede romper el build silenciosamente.
Cuando termine sin errores:
npm run build
Esto compila el backend (NestJS) y el frontend (Vite). Verás warnings sobre el tamaño del bundle (Some chunks are larger than 500 kB) — también ruido, ignóralos.
11. Verificar la versión
head -n 3 package.json | grep version
Debe coincidir con $VERSION.
12. Configurar el .env.local
Aquí está el corazón del cambio respecto a v0.15.x. No edites el .env que viene en el repo: ese fichero está trackeado por git y se actualiza con cada release, así que cualquier cambio tuyo lo perderías al próximo merge. Toda configuración local va en .env.local, que está en .gitignore y persiste entre upgrades.
Como thunderhub:
nano .env.local
Asegúrate de que tu .env.local contiene al menos las siguientes líneas (sustituyendo los valores por los que generaste antes):
# Comentar o eliminar la línea ACCOUNT_CONFIG_PATH si la tenías
# ACCOUNT_CONFIG_PATH='/home/thunderhub/thunderhub/thubConfig.yaml'
DB_TYPE='postgres'
DB_POSTGRES_URL='postgresql://thunderhub:LA_PASSWORD_QUE_GENERASTE@127.0.0.1:5432/thunderhub'
DB_ENCRYPTION_KEY='LOS_64_HEX_QUE_GENERASTE'
Guarda y cierra. Ajusta los permisos:
chmod 600 .env.local
El chmod 600 es importante: la password de Postgres y la encryption key viven en este fichero. Solo thunderhub debe poder leerlo.
13. Salir y arrancar el servicio
exit
sudo systemctl start thunderhub
sudo journalctl -fu thunderhub
14. Verificaciones críticas en el log
Busca estas líneas en los primeros segundos:
Getting production env variables.
[Nest] ... [DatabaseProvider] Running PostgreSQL migrations...
[Nest] ... [DatabaseProvider] PostgreSQL migrations complete.
[Nest] ... LOG [NestApplication] Nest application successfully started
Application is running on: http://[::1]:3001
Si en lugar de production ves development, el override de systemd no se aplicó. Revisa /etc/systemd/system/thunderhub.service.d/override.conf y haz sudo systemctl daemon-reload && sudo systemctl restart thunderhub.
Si las dos líneas de migración (Running + complete) no aparecen, la base de datos no se está activando. Revisa cat /home/thunderhub/thunderhub/.env.local:
- ¿Está bien escrito
DB_TYPE='postgres'? - ¿La URL apunta a
127.0.0.1:5432? - ¿La password no tiene caracteres raros sin escapar?
Si ves un error tipo relation "__drizzle_migrations" already exists, skipping, eso es normal — Drizzle solo crea esa tabla la primera vez; en arranques siguientes la salta.
Cuando todo aparece, sal con Ctrl+C.
Setup inicial post-upgrade
Hasta aquí la “actualización del software”. Pero como esta vez activamos la BD por primera vez, hay un paso adicional que solo se hace una vez en la vida del nodo: crear la cuenta de usuario y conectar el nodo LND.
15. Crear el primer usuario en /setup
Abre el navegador en la URL de tu ThunderHub. Si no la recuerdas, en minibolt suele ser https://<ip-de-tu-nodo>:4002 (con HTTPS auto-firmado, acepta el certificado).
ThunderHub te debe redirigir automáticamente a /setup. Si por lo que sea no lo hace y ves la pantalla de “Welcome to ThunderHub”, añade /setup a mano en la barra de direcciones.
Verás un formulario de Initial Setup con tres campos:
- Email: el que tú quieras. No se valida contra ningún servicio externo, es solo el identificador de tu login. Algo tipo
tu-nombre@minibolt.localvale perfectamente. - Password: una password fuerte, no la del YAML antiguo. Apúntala donde la apuntes — sin esto no puedes volver a entrar.
- Confirm Password: lo mismo.
Click en crear. Te redirigirá automáticamente a /login.
16. Loguearte como usuario DB
En la pantalla de login verás un formulario “Account Login” con email y password. Mete los que acabas de crear y entra.
Como aún no tienes ningún nodo configurado en la BD, te redirigirá automáticamente a /node-setup con un formulario “Connect a Node”.
17. Conectar tu nodo LND
Necesitas dos valores en formato hex: el admin.macaroon y el tls.cert de tu LND. En otra terminal, como admin:
sudo -u thunderhub xxd -ps -u -c 1000 /data/lnd/data/chain/bitcoin/mainnet/admin.macaroon | tr -d '\n'; echo
echo "---"
sudo -u thunderhub xxd -ps -u -c 1000 /data/lnd/tls.cert | tr -d '\n'; echo
Te escupe dos líneas largas. Cópialas (el primero es macaroon, el segundo cert). Estos comandos solo leen los ficheros — no crean ni modifican nada en /data/lnd/. Lo único que hacen es imprimir el contenido en hex por la terminal.
Si te da Permission denied, el usuario thunderhub no está en el grupo lnd. Como admin:
sudo usermod -aG lnd thunderhub
sudo systemctl restart thunderhub
Y vuelve a probar.
Vuelta al formulario “Connect a Node” en el navegador, rellena los cinco campos:
- Node Type: LND
- Node Name: el que quieras, por ejemplo
minibolt - Socket:
127.0.0.1:10009(el puerto gRPC de LND, no el REST8080) - Admin Macaroon: el primer hex
- TLS Certificate: el segundo hex (no lo dejes vacío aunque diga “optional”)
Click en Connect Node. Si va bien, te redirigirá al dashboard con tu balance, peers, canales, etc.
Si te da error self-signed certificate o similar, salta a la siguiente sección. Es muy probablemente un problema con DB_ENCRYPTION_KEY.
Por qué DB_ENCRYPTION_KEY merece una sección entera
Esta es la trampa silenciosa de v0.16+ que perdí literalmente horas debuggeando. La explico en detalle porque no está documentada en ningún sitio público de manera clara.
Cuando tienes la base de datos activa y añades un nodo Lightning a través del formulario “Connect a Node”, ThunderHub tiene que guardar tu admin.macaroon y tu tls.cert en la tabla nodes de Postgres. Esos valores son secretos críticos — el admin macaroon es literalmente “control total de tu nodo Lightning”. Tiene sentido que se almacenen cifrados.
Para cifrar, ThunderHub usa la variable de entorno DB_ENCRYPTION_KEY. El código relevante (en user.service.ts) hace algo así:
const encryptedMacaroon = encryptionKey
? encryptValue(input.macaroon, encryptionKey)
: input.macaroon; // ← si no hay key, guarda en plano
Es decir: si DB_ENCRYPTION_KEY no está definida, el macaroon se guarda en plano (sin cifrar) en la tabla. No falla. No avisa. Solo lo guarda tal cual.
Hasta aquí, “raro pero no roto”. Lo siguiente sí está roto. Cuando el nodo va a usarse, el código (en accounts.service.ts) hace:
const macaroon = node.encrypted_macaroon && encryptionKey
? decryptValue(node.encrypted_macaroon, encryptionKey)
: undefined;
Mira la condición: si encryptionKey no está definida, devuelve undefined aunque la columna encrypted_macaroon tenga datos. Lo mismo para el cert. La intención del código era “si la columna está vacía, devuelve undefined”, pero la implementación trata encryptionKey como condición necesaria.
Resultado: tu macaroon y tu cert están sentados en la BD en plano, pero el código nunca los lee. La conexión gRPC a LND se hace con cert=undefined, falla la verificación TLS, y el log se llena de:
Error: GetWalletInfoErr. No connection established.
Last error: Error: self-signed certificate. Resolution note:
Cada 60 segundos. Sin pista alguna en el mensaje de error de que el problema es una variable de entorno faltante.
Para arreglarlo: define DB_ENCRYPTION_KEY en .env.local, borra los nodos mal guardados de la BD (porque el formato del campo asume cifrado y va a confundir al sistema), y vuelve a añadir el nodo desde la UI. Como thunderhub:
psql "$DB_POSTGRES_URL" <<'SQL'
DELETE FROM channel_metadata;
DELETE FROM user_nodes;
DELETE FROM nodes;
SQL
Y reinicia. Tras reiniciar, vuelve al /node-setup y mete el nodo otra vez. Esta vez, con la variable definida, el encryptValue() funciona y el decryptValue() también.
Backup de la clave: DB_ENCRYPTION_KEY no se puede regenerar. Si la pierdes (después de haber cifrado nodos con ella), todos los macaroons cifrados en la BD quedan irrecuperables — tendrías que borrar la tabla nodes y volver a meter los nodos a mano. Apúntala en tu gestor de contraseñas junto a la password del Postgres.
Para el mantenedor: este comportamiento debería ser, mínimo, un warning explícito al arrancar; idealmente, un fail-fast con mensaje claro tipo “DB enabled but DB_ENCRYPTION_KEY not set; refusing to start to avoid storing secrets in plaintext”. Si te apetece reportarlo en apotdevin/thunderhub con referencia a esta guía, ayudas a quien venga detrás.
Cómo usar la feature de notas por canal
Una vez conectado el nodo y con la dashboard cargando datos reales, vete a la página de canales (Channels). En v0.18 la columna Note está oculta por defecto. Búscala en el toggler de columnas (suele ser un menú “Columns” o un icono de columnas arriba a la derecha de la tabla) y actívala.
A partir de ahí, click en la celda de un canal cualquiera, escribe el comentario que quieras (liquidity ring X, peer pagador lento, revisar fees Q3, lo que te haga falta), y se guarda solo. Persiste al recargar y al reiniciar el servicio.
Para verificarlo desde SQL si tienes curiosidad, como admin:
sudo -u thunderhub psql "$DB_POSTGRES_URL" -c "SELECT * FROM channel_metadata;"
Verás una fila por nota, scoped por (user_id, node_id, channel_id).
Solución de problemas
“Error: GetWalletInfoErr … self-signed certificate” en bucle cada 60 segundos
99% de las veces: DB_ENCRYPTION_KEY no definida. Sigue el procedimiento de la sección anterior.
1% restante: el thunderhub no puede leer /data/lnd/tls.cert. Verifica con sudo -u thunderhub head -2 /data/lnd/tls.cert. Si te da Permission denied, añade thunderhub al grupo lnd con sudo usermod -aG lnd thunderhub y reinicia el servicio.
Pantalla “Welcome to ThunderHub” cuando deberías ver la lista de cuentas
Significa que el GraphQL get_server_accounts está devolviendo array vacío. Causas:
- Has navegado a
/loginantes de completar/setup. Solución: ve a/setupmanualmente y crea el usuario. - Tu
.env.localno se está leyendo. Verifica concat .env.localy reinicia. - Browser cache. Hard refresh con Ctrl+Shift+R.
- La cuenta YAML tiene errores y no se cargó. Mira los logs del último arranque buscando
Server accounts that will be available:. Si esa línea no aparece, el YAML falló al parsearse — pero como en esta guía retiramos el YAML, no debería ser tu caso.
“Your local changes to the following files would be overwritten by merge”
Te lo da package-lock.json o schema.gql. Solución limpia:
git checkout -- package-lock.json schema.gql
git merge v$VERSION
“gpg: Can’t check signature: No public key” con clave B5690EEEBB952194
Te falta importar la de GitHub web-flow. Como thunderhub:
curl https://github.com/web-flow.gpg | gpg --import
Y vuelve a verificar.
“sh: 1: rimraf: not found” durante npm run build
Significa que el npm install anterior falló a mitad. Borra node_modules y reinstala:
rm -rf node_modules
npm install
El servicio arranca pero isProduction: false en el log
El override de systemd no se aplicó. Revisa:
sudo cat /etc/systemd/system/thunderhub.service.d/override.conf
Debe mostrar:
[Service]
Environment="NODE_ENV=production"
Si no, recréalo con el bloque tee del setup inicial y sudo systemctl daemon-reload && sudo systemctl restart thunderhub.
Postgres rechaza la conexión: “FATAL: Peer authentication failed”
Tu pg_hba.conf está configurado solo para autenticación peer (por usuario del sistema), no md5/scram-sha-256 (por contraseña). Como admin, edita:
sudo nano /etc/postgresql/*/main/pg_hba.conf
Y asegúrate de que existe esta línea (o cámbiala si está):
host thunderhub thunderhub 127.0.0.1/32 scram-sha-256
Luego:
sudo systemctl reload postgresql
Si todo lo demás falla
Antes de la opción nuclear (desinstalar y reinstalar), prueba:
rm -rf node_modules package-lock.json dist src/client/dist
git checkout -- package-lock.json
npm install
npm run build
Y si tampoco, vuelve al SHA pre-upgrade. Si tuviste la disciplina de guardarlo:
git rev-parse HEAD > /tmp/thunderhub-pre-install.txt # antes de la actualización
# ...para volver atrás...
git checkout $(cat /tmp/thunderhub-pre-install.txt)
Procedimiento resumido (chuleta)
Cuando ya tengas todo el setup hecho y solo quieras actualizar a una versión futura, esto es todo lo que necesitas:
# Como admin
sudo systemctl stop thunderhub
sudo su - thunderhub
cd thunderhub
VERSION=0.X.Y # ← cambia
git checkout -- package-lock.json schema.gql 2>/dev/null
git fetch https://github.com/apotdevin/thunderhub.git tag v$VERSION
git verify-commit v$VERSION^{commit} # confirma "Good signature"
git merge v$VERSION
less CHANGELOG.md
# Solo en saltos de minor o mayor:
rm -rf node_modules dist src/client/dist
npm install
npm run build
head -n 3 package.json | grep version
exit
sudo systemctl start thunderhub
sudo journalctl -fu thunderhub | grep -E 'production|migrations|started'
Verifica en el log:
Getting production env variables.PostgreSQL migrations complete.Nest application successfully started
Y abre la web. Login con tu email/password DB y al dashboard.
Por qué esto importa
Tu nodo Lightning gestiona dinero real. Cada actualización es una oportunidad para que código nuevo entre en él. Sin verificación de firmas confías en que GitHub no esté comprometido, en que la cuenta del mantenedor no esté hackeada, y en que tu conexión TLS al servidor de GitHub sea íntegra. Verificar la firma GPG del commit del tag reduce esa cadena de confianza a un único punto: la clave del mantenedor en tu keyring local.
Sobre NODE_ENV=production: ya lo expliqué en la guía anterior, pero como esto es para gente que viene de v0.15.x, lo repito. ThunderHub asume que el operador conoce el estado de su entorno. Si no se lo dices, asume que estás en desarrollo y usa secretos hardcodeados. Esto no es un fallo per se, es una decisión de diseño que descarga la responsabilidad sobre quien despliega. Tú tomas la responsabilidad poniendo el override.
Sobre DB_ENCRYPTION_KEY: esto sí es algo que me parece que debería corregirse upstream. Hay dos comportamientos a la vez problemáticos: que ThunderHub guarde secretos en plano cuando la clave no está, y que luego silenciosamente se “olvide” de leerlos cuando intenta conectar. Cualquiera de las dos cosas, sola, sería un bug menor; las dos juntas producen un fallo críptico (self-signed certificate) que aparenta ser un problema de TLS cuando es un problema de configuración. La forma defensiva sería: ThunderHub se niega a arrancar si DB_TYPE está set y DB_ENCRYPTION_KEY no, con un error explícito. O al menos: warning fuerte al arrancar, y un mensaje en la UI cuando se añade un nodo si la BD no está cifrada.
Sobre el cambio de paradigma YAML → DB: el modelo viejo (un YAML con master password y cuentas) era simple y funcionaba. El modelo nuevo (Postgres con users, teams, nodes, channel_metadata) habilita features que el viejo no permitía: persistencia de notas, gestión multiusuario, soporte de equipos, integración nativa con Magma, y más. El precio es complejidad operativa: ahora tienes una BD que mantener, una password que rotar periódicamente, una clave de cifrado que custodiar. Para un nodo personal de un único operador, el coste/beneficio es discutible. Para un nodo con varios operadores o features avanzadas (notas, equipos, asset management), claramente vale la pena.
Si encuentras erratas, mejoras, o casos no cubiertos, te leo. 🤙
Esta guía cubre v0.18.0. Para versiones futuras, los pasos del procedimiento resumido siguen siendo válidos; el setup único (GPG + NODE_ENV + Postgres + DB_ENCRYPTION_KEY) ya no necesitas repetirlo.
Write a comment