feat: add Linux arm64 AppImage support for SBC users (Pi, Orange Pi, etc.)#3441
feat: add Linux arm64 AppImage support for SBC users (Pi, Orange Pi, etc.)#3441toastmanAu wants to merge 1 commit into
Conversation
Testing Results — Tested on arm64 hardwareOrange Pi 5 (RK3588, aarch64) — Ubuntu 22.04✅ AppImage launches and renders correctly Screenshot of welcome screen (running on Pi 5):
Log output confirms:
Known Issues / Notes1. Auto-updater 404 (expected) The updater looks for 2. sudo apt install zlib1g-devOr: 3. GPU / SwiftShader fallback Tested build: |
|
Bumping this for visibility — happy to address any feedback or adjust the implementation if needed. For context on the broader motivation: we've been building community tooling to lower the barrier for ARM-based node deployment on the Nervos network (Orange Pi, Raspberry Pi, etc.), and just filed a related request on the Fiber repo (nervosnetwork/fiber#1186) for aarch64 prebuilt binaries there too. Neuron arm64 support would complete the picture for users wanting a full desktop wallet experience on these devices. Would love to know if this is something the team would consider merging, or if there are concerns we can address. |
|
Thanks @toastmanAu! |
|
|
||
| curl -O -L "${GITHUB_RELEASE_URL}/${CKB_VERSION}/${CKB_FILENAME}.tar.gz" | ||
| tar xvzf ${CKB_FILENAME}.tar.gz | ||
| cp ${CKB_FILENAME}/ckb ./ckb-arm64 |
There was a problem hiding this comment.
This adds bin/linux/ckb-arm64 as an unconditional Linux extraFile and also asks electron-builder to build both x64 and arm64 from the same Linux packaging config.
In the current workflows, Linux packaging package.yml and package_for_test.yml calls ./scripts/download-ckb.sh without arguments, which only prepares the x64 bin/linux/ckb path. So the existing x64 Linux packaging path can fail because bin/linux/ckb-arm64 is missing.
Even when an arm64 AppImage is built manually, the app would still launch packaged bin/ckb here
neuron/packages/neuron-wallet/src/services/ckb-runner.ts
Lines 41 to 55 in d32bb9a
bin/ckb-arm64 does not make the full node use it.
I think the cleaner fix is to keep the packaged runtime path architecture-neutral: always bundle exactly one CKB binary as bin/ckb. Then make the build input architecture-specific: download-ckb.sh linux prepares the x64 binary as bin/linux/ckb, and download-ckb.sh linux-arm64 prepares the arm64 binary as the same bin/linux/ckb path. The release/test scripts can then add explicit linux-arm64 cases that run electron-builder --linux --arm64. This avoids breaking the existing x64 packaging path and keeps the runtime lookup unchanged.
There was a problem hiding this comment.
maybe like this:
diff --git a/packages/neuron-wallet/electron-builder.yml b/packages/neuron-wallet/electron-builder.yml
index 55aa42bc..4e7e6dda 100644
--- a/packages/neuron-wallet/electron-builder.yml
+++ b/packages/neuron-wallet/electron-builder.yml
@@ -88,10 +88,6 @@ linux:
extraFiles:
- from: "bin/linux/ckb"
to: "bin/ckb"
- filter: "**/*"
- - from: "bin/linux/ckb-arm64"
- to: "bin/ckb-arm64"
- filter: "**/*"
- from: "bin/linux/ckb-light-client"
to: "bin/ckb-light-client"
- from: "light/ckb_light_testnet.toml"
@@ -99,7 +95,4 @@ linux:
- from: "light/ckb_light_mainnet.toml"
to: "light/ckb_light_mainnet.toml"
target:
- - target: AppImage
- arch:
- - x64
- - arm64
+ - AppImage
diff --git a/scripts/download-ckb.sh b/scripts/download-ckb.sh
index 7710c9a9..e635479f 100755
--- a/scripts/download-ckb.sh
+++ b/scripts/download-ckb.sh
@@ -66,7 +66,7 @@ function download_linux_aarch64() {
curl -O -L "${GITHUB_RELEASE_URL}/${CKB_VERSION}/${CKB_FILENAME}.tar.gz"
tar xvzf ${CKB_FILENAME}.tar.gz
- cp ${CKB_FILENAME}/ckb ./ckb-arm64
+ cp ${CKB_FILENAME}/ckb ./ckb
rm -rf $CKB_FILENAME
rm ${CKB_FILENAME}.tar.gz
}
@@ -111,7 +111,7 @@ function download_windows_light() {
case $1 in
mac) download_macos; download_macos_light;;
- linux) download_linux; download_linux_aarch64; download_linux_light;;
+ linux) download_linux; download_linux_light;;
linux-arm64) download_linux_aarch64; download_linux_light;;
win) download_windows; download_windows_light;;
*)
diff --git a/scripts/package-for-test.sh b/scripts/package-for-test.sh
index 34415589..e4401c3f 100755
--- a/scripts/package-for-test.sh
+++ b/scripts/package-for-test.sh
@@ -11,6 +11,9 @@ function package() {
linux)
electron-builder --linux -p never
;;
+ linux-arm64)
+ electron-builder --linux --arm64 -p never
+ ;;
*)
electron-builder -mwl -p never
;;
diff --git a/scripts/release.sh b/scripts/release.sh
index 4ce8ca38..27479dbc 100755
--- a/scripts/release.sh
+++ b/scripts/release.sh
@@ -11,6 +11,9 @@ function release() {
linux)
electron-builder --linux -p always
;;
+ linux-arm64)
+ electron-builder --linux --arm64 -p always
+ ;;
*)
electron-builder -mwl -p always
;;
| linux-arm64) download_linux_aarch64; download_linux_light;; | ||
| ``` | ||
|
|
||
| > **Note on `ckb-light-client`**: No arm64 Linux release exists in the `ckb-light-client` repo yet. The x86_64 binary is currently used for both architectures. A separate issue/PR to the `ckb-light-client` repo would complete that gap. |
There was a problem hiding this comment.
I will add a fix to support arm64 Linux release for ckb-light-client.
There was a problem hiding this comment.
oh, we already had this nervosnetwork/ckb-light-client#265, it's still in rc stage.
There was a problem hiding this comment.
Once ckb-light-client is updated, I'll release another release build that includes aarch64 support.
3 participants
Add Linux arm64 (aarch64) AppImage support
Summary
This PR adds support for building Neuron as a Linux arm64 AppImage, targeting Raspberry Pi 4/5, Orange Pi, ROCK series boards and other aarch64 single-board computers running Linux — which are popular in the CKB node-running community.
A working
Neuron-v0.204.0-arm64.AppImage(192 MB, verified ELF aarch64) was built successfully on an Orange Pi 5 (aarch64, Ubuntu 22.04) using the changes in this PR.Changes
1.
scripts/download-ckb.sh— adddownload_linux_aarch64()Added a new function that downloads the
aarch64-unknown-linux-gnuCKB binary (which already exists in every CKB release) and saves it asbin/linux/ckb-arm64:Also added a
linux-arm64case to the switch:2.
packages/neuron-wallet/electron-builder.yml— add arm64 target + extraFile3.
package.yml(GitHub Actions) — add arm64 Linux runnerTo build the arm64 AppImage in CI, add an
ubuntu-24.04-armrunner to the matrix:And add a conditional upload step:
Build instructions (manual, on arm64 Linux)
Output:
release/Neuron-v{version}-arm64.AppImageFlags explained:
--linux --arm64: target platform and architecture--config.npmRebuild=false: skip native module rebuild (avoids cross-compilation issues when building arm64 on an arm64 host where modules are already built for the right arch)Tested on
Neuron-v0.204.0-arm64.AppImagebuilt, 192 MBThe resulting AppImage is a valid ELF aarch64 executable:
Why this matters
Single-board computers (Raspberry Pi 4/5, Orange Pi, Rock Pi, etc.) are widely used to run CKB full nodes — they're low-power, always-on, and affordable. Many CKB community members running nodes on these devices also want to use Neuron as their wallet but currently have no official binary. An arm64 AppImage closes that gap with a single self-contained download.