From b23eb32892f1e29519d3974070c0cabc68417632 Mon Sep 17 00:00:00 2001 From: Matt Hill <9935159+MattDHill@users.noreply.github.com> Date: Tue, 11 Aug 2026 11:40:57 -0600 Subject: [PATCH 1/3] =?UTF-8?q?docs(start-docs):=20correct=20the=20LND=20m?= =?UTF-8?q?igration=20guide=20=E2=80=94=20drop=20RaspiBlitz,=20add=20myNod?= =?UTF-8?q?e?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The published page listed RaspiBlitz and myNode as supported and named four separate per-platform actions. None of that matches the 0.4 LND package: there is one Initialize Wallet action with a method selector, RaspiBlitz was never carried over, and myNode is only supported as of lnd-startos 0.21.1-beta:12. StartOS-to-StartOS, which has worked all along, was missing from the page entirely. Rewrites the platform list, the action names, and the steps around them, including the Bitcoin backend task and the bolt-to-SQLite conversion that now runs before an imported node starts. The claim that starting the service creates a wallet is also gone — in 0.4 the wallet is created by the action, and it is an existing wallet that blocks a migration. Replaces the hand-copy instructions with the safe route for an unsupported platform: close channels first and recover on-chain. Co-Authored-By: Claude Opus 5 (1M context) (cherry picked from commit b3fc628a27c48f1190c35ae4091097cd77418f17) --- .../start-docs/bitcoin-guides/src/README.md | 2 +- .../bitcoin-guides/src/lnd-migration.md | 65 +++++++++++-------- 2 files changed, 39 insertions(+), 28 deletions(-) diff --git a/projects/start-docs/bitcoin-guides/src/README.md b/projects/start-docs/bitcoin-guides/src/README.md index 40e0a9fe5c..f6f1c24c0c 100644 --- a/projects/start-docs/bitcoin-guides/src/README.md +++ b/projects/start-docs/bitcoin-guides/src/README.md @@ -20,7 +20,7 @@ StartOS makes this practical. Install a Bitcoin node from the StartOS Marketplac - **[Lightning Wallets](lightning-wallets.md)** — Native apps and self-hosted web tools for managing your LND or Core Lightning node, including RTL, ThunderHub, Zeus, Alby Hub, and more. -- **[Migrating LND to StartOS](lnd-migration.md)** — How to transfer your LND node from Umbrel, RaspiBlitz, myNode, or another platform to StartOS without closing channels. +- **[Migrating LND to StartOS](lnd-migration.md)** — How to transfer your LND node from Umbrel, myNode, or another StartOS server without closing channels. ## Supported Implementations diff --git a/projects/start-docs/bitcoin-guides/src/lnd-migration.md b/projects/start-docs/bitcoin-guides/src/lnd-migration.md index 7fc072eda3..15aae2540d 100644 --- a/projects/start-docs/bitcoin-guides/src/lnd-migration.md +++ b/projects/start-docs/bitcoin-guides/src/lnd-migration.md @@ -10,68 +10,79 @@ How to transfer your LND node — including on-chain funds and open Lightning ch StartOS's LND service can pull wallet and channel data directly from the following platforms over your local network: -- **Umbrel** (1.x and 0.5.x) -- **RaspiBlitz** +- **Umbrel** 1.x - **myNode** +- **another StartOS server** -If your source platform is not listed, you may still be able to migrate by manually copying the LND data directory. See [Manual Migration](#manual-migration) below. +If your source platform is not listed, see [Other Platforms](#other-platforms) below. ## Prerequisites - Both devices (source node and StartOS server) must be on the **same local network**. -- Your source node must be **running and accessible** at the time of migration. -- You need your source node's **local IP address** (check your router's admin page if unsure). -- You need your source node's **password(s)** for SSH or API access, depending on the platform. +- Your source node must be **running and reachable** at the time of migration. +- You need your source node's **local IP address or `.local` hostname** (check your router's admin page if unsure). +- You need the password the migration signs in with: + +| Source | Password to enter | +| --------------- | ------------------------------------------------------------------------------- | +| Umbrel | The password for your Umbrel dashboard, which is also its SSH password | +| myNode | The password for myNode's `admin` user, used for both SSH and the web interface | +| Another StartOS | That server's master password | + +You do not need your source node's LND wallet password. The migration reads it from the origin and carries it across, so StartOS can unlock the wallet you already have. ## Migration Steps ### 1. Install LND on StartOS -Install LND from the StartOS Marketplace, but **do not start it**. Starting the service creates a new wallet, which prevents the migration action from running. If you have already started LND, uninstall it and install a fresh copy. +Install LND from the StartOS Marketplace, but **do not start it**. LND posts two critical tasks on install and cannot be started until both are done — leave them for now. -### 2. Run the Migration Action +The migration refuses to run if a wallet already exists on this server, so if you have already created one with **Start Fresh**, uninstall LND and install a fresh copy. -Open LND on your StartOS server and go to **Actions**. Select the migration action that matches your source platform: +### 2. Run the Migration -- **Migrate from Umbrel 1.x** -- **Migrate from Umbrel 0.5** -- **Migrate from RaspiBlitz** +Open LND on your StartOS server, go to **Actions**, and run **Initialize Wallet**. Under **Initialization Method**, choose the option matching your source platform: + +- **Migrate from Umbrel** - **Migrate from myNode** +- **Migrate from StartOS** -Enter your source node's local IP address and any required passwords when prompted. +Enter your source node's address and password, then submit. ### 3. Wait for the Migration to Complete -The migration will copy your LND wallet, channel database, and configuration from the source node. This may take several minutes depending on the size of your channel database and network speed. +The migration shuts down the services on your source node, copies LND's wallet, channel database and configuration across, and adopts its wallet password. This can take anywhere from a few minutes to a few hours, depending on the size of your channel database and the speed of your network and the source node's disk. Leave the action running until it reports success. ### 4. Disconnect the Old Node -Once the migration is complete, **shut down and disconnect your old node** before proceeding. This is critical — running two nodes with the same channel state will result in force-closures and potential loss of funds. +Once the migration reports success, **shut down and disconnect your old node** before proceeding. This is critical — running two nodes with the same channel state will result in force-closures and potential loss of funds. + +The migration stops the source node's services as its first step, and the StartOS source is left with LND uninstalled, but only powering the device down guarantees it stays off. -### 5. Start LND on StartOS +### 5. Choose a Bitcoin Backend and Start LND -With the old node safely shut down, start LND on your StartOS server. It will begin syncing and reconnecting to your peers with the migrated channel state. +With the old node safely shut down, complete LND's second critical task by running **Bitcoin Backend**: pick **Bitcoin** if you run a Bitcoin node on this server (recommended), or **Neutrino** to use the built-in light client. + +Then start LND. Umbrel, myNode and pre-0.21 StartOS nodes all run LND's older `bolt` database, which StartOS converts to SQLite before the service comes up. On a large channel database this conversion can itself take hours; LND reports which stage it is on while it runs, and the service will not finish starting until it is done. Leave it alone until it does. + +LND will then begin syncing and reconnecting to your peers with the migrated channel state. > [!WARNING] > > Never restart your old node after the migration has completed. If you need to go back to your old node for any reason, do **not** start LND on StartOS first. -## Manual Migration +## Other Platforms -If your source platform is not listed above, you can migrate by manually copying the LND data directory. The key files are: +There is no built-in migration for platforms outside the list above — including RaspiBlitz, which earlier StartOS releases supported and current ones do not. -- `wallet.db` — Your on-chain wallet -- `channel.backup` — Static channel backups (SCB) -- `data/graph/mainnet/channel.db` — Channel state database +The safe route from an unsupported platform is to **close your channels on the old node first**, letting the balances settle on-chain, and then recover the on-chain funds on StartOS. Run **Initialize Wallet → Start Fresh** on StartOS and send the funds over from your old wallet, or restore your old node's seed into an on-chain wallet of your choice. This costs you your channels and the fees to re-open them, but it carries none of the force-close risk of moving channel state by hand. -> [!NOTE] -> -> Manual migration carries more risk than the built-in actions. If you are unsure about the process, consider closing your channels on the old node first, then restoring from seed on StartOS. This is safer but requires re-opening channels. +Copying an LND data directory across by hand is possible — it is what the built-in migrations do — but there is no supported path for it, and a partial or inconsistent copy of a channel database force-closes channels rather than failing safely. If you intend to try it anyway, the source and destination paths each migration uses are documented in the [LND package README](https://github.com/Start9Labs/lnd-startos#initialize-wallet). ## Troubleshooting -**"Import action not available"** — LND has already been started and a wallet exists. Uninstall LND and install a fresh copy from the StartOS Marketplace. +**The migration option is missing, or the action refuses to run** — LND already has a wallet, or the service has been started. Uninstall LND and install a fresh copy from the StartOS Marketplace. -**Migration times out or fails** — Ensure both devices are on the same local network and that the source node is running. Double-check the IP address and passwords. +**Migration times out or fails** — Ensure both devices are on the same local network and that the source node is running. Double-check the address and password. A failed migration leaves no wallet behind, so you can correct the details and run the action again. **Channels force-close after migration** — This usually means the old node was restarted after migration, or the channel database was corrupted during transfer. Unfortunately, force-closed channels cannot be recovered — the funds will be returned to your on-chain wallet after the timelock expires. From a580b9bcdc6d19d7549e51cf69307aad276a29d7 Mon Sep 17 00:00:00 2001 From: Matt Hill <9935159+MattDHill@users.noreply.github.com> Date: Tue, 11 Aug 2026 15:56:13 -0600 Subject: [PATCH 2/3] docs(start-docs): update the LND migration guide to the schedule-then-start flow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The action no longer performs the copy: it verifies it can sign in to the origin and schedules the migration, and starting LND stops the origin, copies the data, converts the database, and comes online — with progress under Health Checks (Wallet Import, then Database Conversion). Reorder the steps to match (backend before start; disconnect the old node after the migration completes, since the origin must be reachable when LND starts), reach Initialize Wallet via its task rather than an Actions menu it does not appear in, note that stopping LND mid-migration resumes safely and that rebooting a migrated Umbrel or myNode brings its LND back, and split troubleshooting into submit-time and start-time failures. Matches Start9Labs/lnd-startos#178 as it ships in 0.21.1-beta:12. Co-Authored-By: Claude Fable 5 (cherry picked from commit b78ebb72cb19472bd0cce012b3fb317e9dcbeee7) --- .../bitcoin-guides/src/lnd-migration.md | 32 ++++++++++--------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/projects/start-docs/bitcoin-guides/src/lnd-migration.md b/projects/start-docs/bitcoin-guides/src/lnd-migration.md index 15aae2540d..2610bc1c73 100644 --- a/projects/start-docs/bitcoin-guides/src/lnd-migration.md +++ b/projects/start-docs/bitcoin-guides/src/lnd-migration.md @@ -19,7 +19,7 @@ If your source platform is not listed, see [Other Platforms](#other-platforms) b ## Prerequisites - Both devices (source node and StartOS server) must be on the **same local network**. -- Your source node must be **running and reachable** at the time of migration. +- Your source node must be **running and reachable** when you schedule the migration and when you start LND — the copy happens at startup. - You need your source node's **local IP address or `.local` hostname** (check your router's admin page if unsure). - You need the password the migration signs in with: @@ -39,33 +39,33 @@ Install LND from the StartOS Marketplace, but **do not start it**. LND posts two The migration refuses to run if a wallet already exists on this server, so if you have already created one with **Start Fresh**, uninstall LND and install a fresh copy. -### 2. Run the Migration +### 2. Schedule the Migration -Open LND on your StartOS server, go to **Actions**, and run **Initialize Wallet**. Under **Initialization Method**, choose the option matching your source platform: +Open LND on your StartOS server and run its **Initialize Wallet** task. Under **Initialization Method**, choose the option matching your source platform: - **Migrate from Umbrel** - **Migrate from myNode** - **Migrate from StartOS** -Enter your source node's address and password, then submit. +Enter your source node's address and password, then submit. The task signs in to your source node to verify the address and password work — a wrong password or unreachable node fails here, within seconds, and you can correct the details and run the task again. On success the migration is scheduled: nothing has been copied yet, and your source node is still running. -### 3. Wait for the Migration to Complete +### 3. Choose a Bitcoin Backend -The migration shuts down the services on your source node, copies LND's wallet, channel database and configuration across, and adopts its wallet password. This can take anywhere from a few minutes to a few hours, depending on the size of your channel database and the speed of your network and the source node's disk. Leave the action running until it reports success. +Complete LND's second task by running **Bitcoin Backend**: pick **Bitcoin** if you run a Bitcoin node on this server (recommended), or **Neutrino** to use the built-in light client. -### 4. Disconnect the Old Node +### 4. Start LND — This Runs the Migration -Once the migration reports success, **shut down and disconnect your old node** before proceeding. This is critical — running two nodes with the same channel state will result in force-closures and potential loss of funds. +Start LND. The migration runs as part of startup: it stops the services on your source node, copies LND's wallet and channel database across your local network, converts the database to LND's current SQLite backend (Umbrel, myNode and pre-0.21 StartOS nodes all run the older `bolt` format), and then brings LND online. Watch its progress under **Health Checks** — first **Wallet Import**, then **Database Conversion**. -The migration stops the source node's services as its first step, and the StartOS source is left with LND uninstalled, but only powering the device down guarantees it stays off. +The copy and conversion together can take anywhere from a few minutes to several hours, depending on the size of your channel database and the speed of your network and the source node's disk. Leave LND running until it comes online. Stopping LND mid-migration is safe — it picks up where it left off on the next start. -### 5. Choose a Bitcoin Backend and Start LND +### 5. Disconnect the Old Node -With the old node safely shut down, complete LND's second critical task by running **Bitcoin Backend**: pick **Bitcoin** if you run a Bitcoin node on this server (recommended), or **Neutrino** to use the built-in light client. +Once LND is online with your migrated wallet, **shut down and disconnect your old node**. This is critical — running two nodes with the same channel state will result in force-closures and potential loss of funds. -Then start LND. Umbrel, myNode and pre-0.21 StartOS nodes all run LND's older `bolt` database, which StartOS converts to SQLite before the service comes up. On a large channel database this conversion can itself take hours; LND reports which stage it is on while it runs, and the service will not finish starting until it is done. Leave it alone until it does. +The migration stops the source node's services before copying, and a StartOS source is left with LND uninstalled — but only powering the device down guarantees it stays off. In particular, rebooting a migrated Umbrel or myNode brings its LND back. -LND will then begin syncing and reconnecting to your peers with the migrated channel state. +LND will then sync and reconnect to your peers with the migrated channel state. > [!WARNING] > @@ -81,8 +81,10 @@ Copying an LND data directory across by hand is possible — it is what the buil ## Troubleshooting -**The migration option is missing, or the action refuses to run** — LND already has a wallet, or the service has been started. Uninstall LND and install a fresh copy from the StartOS Marketplace. +**The migration option is missing, or the task refuses to run** — LND already has a wallet, or the service has been started. Uninstall LND and install a fresh copy from the StartOS Marketplace. -**Migration times out or fails** — Ensure both devices are on the same local network and that the source node is running. Double-check the address and password. A failed migration leaves no wallet behind, so you can correct the details and run the action again. +**The task fails when submitted** — StartOS could not sign in to your source node. Ensure both devices are on the same local network and the source node is running, then double-check the address and password and run the task again. Nothing has been copied at this point. + +**Wallet Import shows failure after starting LND** — the source node stopped being reachable between scheduling and starting (powered off, address changed, or its services shut down by hand). The migration retries on its own; to intervene, stop LND, bring the source node back online, and start LND again — the migration resumes. **Channels force-close after migration** — This usually means the old node was restarted after migration, or the channel database was corrupted during transfer. Unfortunately, force-closed channels cannot be recovered — the funds will be returned to your on-chain wallet after the timelock expires. From b0a11755bbeae91d8c5aaa2940b47008c2b11b7f Mon Sep 17 00:00:00 2001 From: Matt Hill <9935159+MattDHill@users.noreply.github.com> Date: Tue, 11 Aug 2026 22:09:03 -0600 Subject: [PATCH 3/3] docs(start-docs): LND migration leaves a StartOS origin stopped, not uninstalled MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The import script no longer uninstalls the origin's LND — its data stays as the fallback until the migrated node has proven itself, and a stopped StartOS service stays stopped across reboots. Also note the failure path: after a few failed attempts LND stops itself and re-posts the Initialize Wallet task, which is how the user corrects the details and retries. Co-Authored-By: Claude Fable 5 (cherry picked from commit 2a0561e3484a76a3939eecb27e77a954ce709f7f) --- projects/start-docs/bitcoin-guides/src/lnd-migration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/projects/start-docs/bitcoin-guides/src/lnd-migration.md b/projects/start-docs/bitcoin-guides/src/lnd-migration.md index 2610bc1c73..a5000dd9fc 100644 --- a/projects/start-docs/bitcoin-guides/src/lnd-migration.md +++ b/projects/start-docs/bitcoin-guides/src/lnd-migration.md @@ -63,7 +63,7 @@ The copy and conversion together can take anywhere from a few minutes to several Once LND is online with your migrated wallet, **shut down and disconnect your old node**. This is critical — running two nodes with the same channel state will result in force-closures and potential loss of funds. -The migration stops the source node's services before copying, and a StartOS source is left with LND uninstalled — but only powering the device down guarantees it stays off. In particular, rebooting a migrated Umbrel or myNode brings its LND back. +The migration stops the source node's services before copying — and on a StartOS source that stop persists across reboots — but only powering the device down guarantees it stays off. In particular, rebooting a migrated Umbrel or myNode brings its LND back. LND will then sync and reconnect to your peers with the migrated channel state. @@ -85,6 +85,6 @@ Copying an LND data directory across by hand is possible — it is what the buil **The task fails when submitted** — StartOS could not sign in to your source node. Ensure both devices are on the same local network and the source node is running, then double-check the address and password and run the task again. Nothing has been copied at this point. -**Wallet Import shows failure after starting LND** — the source node stopped being reachable between scheduling and starting (powered off, address changed, or its services shut down by hand). The migration retries on its own; to intervene, stop LND, bring the source node back online, and start LND again — the migration resumes. +**Wallet Import shows failure after starting LND** — the source node stopped being reachable between scheduling and starting (powered off, address changed, or its services shut down by hand). The migration retries a few times on its own; if it keeps failing, LND stops itself and re-posts the **Initialize Wallet** task — bring the source node back online, run the task again with the corrected details, and start LND to retry. **Channels force-close after migration** — This usually means the old node was restarted after migration, or the channel database was corrupted during transfer. Unfortunately, force-closed channels cannot be recovered — the funds will be returned to your on-chain wallet after the timelock expires.