mirror of
https://github.com/The-Low-Code-Foundation/OpenNoodl.git
synced 2026-01-12 15:22:55 +01:00
387 lines
8.4 KiB
Markdown
387 lines
8.4 KiB
Markdown
# Task 7.4: Linux Universal Distribution
|
|
|
|
## Problem Statement
|
|
|
|
Linux support is currently incomplete:
|
|
- Only `.deb` target configured
|
|
- Someone added Arch Linux support (AUR?) but status unclear
|
|
- No AppImage for universal distribution
|
|
- No auto-update support for Linux
|
|
- Native modules (dugite, desktop-trampoline) may have compatibility issues
|
|
|
|
## Goals
|
|
|
|
1. **AppImage**: Universal format that works on any Linux distribution
|
|
2. **.deb**: Native experience for Debian/Ubuntu users (largest desktop Linux market)
|
|
3. **Auto-update**: AppImage supports electron-updater
|
|
4. **Tested**: Verified on Ubuntu 22.04 LTS and 24.04 LTS
|
|
|
|
## Linux Desktop Market Context
|
|
|
|
| Distribution Family | Market Share | Target Format |
|
|
|---------------------|--------------|---------------|
|
|
| Ubuntu/Debian | ~60% | .deb + AppImage |
|
|
| Fedora/RHEL | ~15% | AppImage (RPM optional) |
|
|
| Arch | ~10% | AppImage + AUR |
|
|
| Other | ~15% | AppImage |
|
|
|
|
**Decision**: AppImage as primary (works everywhere), .deb as secondary (native experience for majority).
|
|
|
|
## Implementation
|
|
|
|
### Phase 1: Configure electron-builder for Linux
|
|
|
|
**Step 1.1: Update package.json**
|
|
|
|
```json
|
|
{
|
|
"build": {
|
|
"linux": {
|
|
"target": [
|
|
{
|
|
"target": "AppImage",
|
|
"arch": ["x64"]
|
|
},
|
|
{
|
|
"target": "deb",
|
|
"arch": ["x64"]
|
|
}
|
|
],
|
|
"category": "Development",
|
|
"icon": "build/icons",
|
|
"synopsis": "Visual low-code React development platform",
|
|
"description": "Nodegex is a full-stack low-code platform for building React applications visually.",
|
|
"desktop": {
|
|
"Name": "Nodegex",
|
|
"Comment": "Visual React Development",
|
|
"Categories": "Development;IDE;",
|
|
"Keywords": "react;low-code;visual;programming;node;"
|
|
},
|
|
"mimeTypes": [
|
|
"x-scheme-handler/nodegex"
|
|
]
|
|
},
|
|
|
|
"appImage": {
|
|
"artifactName": "${productName}-${version}-${arch}.AppImage",
|
|
"license": "LICENSE"
|
|
},
|
|
|
|
"deb": {
|
|
"artifactName": "${productName}-${version}-${arch}.deb",
|
|
"depends": [
|
|
"libgtk-3-0",
|
|
"libnotify4",
|
|
"libnss3",
|
|
"libxss1",
|
|
"libxtst6",
|
|
"xdg-utils",
|
|
"libatspi2.0-0",
|
|
"libuuid1",
|
|
"libsecret-1-0"
|
|
],
|
|
"category": "Development"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Phase 2: Handle Native Modules
|
|
|
|
The trickiest part is ensuring dugite's embedded git and desktop-trampoline work on Linux.
|
|
|
|
**Step 2.1: Verify dugite Linux binaries**
|
|
|
|
dugite downloads platform-specific git binaries. Verify they're included:
|
|
|
|
```bash
|
|
# After build, check the AppImage contents
|
|
./Nodegex-1.2.0-x64.AppImage --appimage-extract
|
|
ls -la squashfs-root/resources/app.asar.unpacked/node_modules/dugite/git/
|
|
```
|
|
|
|
**Step 2.2: Check desktop-trampoline**
|
|
|
|
```bash
|
|
ls -la squashfs-root/resources/app.asar.unpacked/node_modules/desktop-trampoline/build/Release/
|
|
file squashfs-root/resources/app.asar.unpacked/node_modules/desktop-trampoline/build/Release/desktop-trampoline
|
|
```
|
|
|
|
**Step 2.3: Verify library dependencies**
|
|
|
|
```bash
|
|
# Check for missing shared libraries
|
|
ldd squashfs-root/resources/app.asar.unpacked/node_modules/dugite/git/bin/git
|
|
ldd squashfs-root/nodegex
|
|
```
|
|
|
|
### Phase 3: AppImage Auto-Update Support
|
|
|
|
AppImage is the only Linux format that supports electron-updater.
|
|
|
|
**Step 3.1: How it works**
|
|
|
|
1. electron-updater checks GitHub Releases for `latest-linux.yml`
|
|
2. Downloads new `.AppImage` to temp location
|
|
3. User confirms restart
|
|
4. New AppImage replaces old one
|
|
5. App restarts
|
|
|
|
**Step 3.2: Required publish config**
|
|
|
|
```json
|
|
{
|
|
"build": {
|
|
"publish": {
|
|
"provider": "github",
|
|
"owner": "the-low-code-foundation",
|
|
"repo": "opennoodl"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Step 3.3: Auto-update behavior**
|
|
|
|
The existing `autoupdater.js` already handles Linux correctly:
|
|
|
|
```javascript
|
|
if (process.platform === 'linux') {
|
|
return; // Currently disabled
|
|
}
|
|
```
|
|
|
|
We need to **enable** it for AppImage:
|
|
|
|
```javascript
|
|
function setupAutoUpdate(window) {
|
|
if (process.env.autoUpdate === 'no') return;
|
|
|
|
// AppImage auto-update works, .deb does not
|
|
if (process.platform === 'linux' && !process.env.APPIMAGE) {
|
|
console.log('Auto-update only available for AppImage');
|
|
return;
|
|
}
|
|
|
|
// ... rest of auto-update logic
|
|
}
|
|
```
|
|
|
|
### Phase 4: Icon Generation
|
|
|
|
Linux needs multiple icon sizes in PNG format.
|
|
|
|
**Step 4.1: Create icon set**
|
|
|
|
```bash
|
|
# From a 1024x1024 source icon
|
|
mkdir -p build/icons
|
|
|
|
for size in 16 24 32 48 64 128 256 512 1024; do
|
|
convert icon-source.png -resize ${size}x${size} build/icons/${size}x${size}.png
|
|
done
|
|
```
|
|
|
|
**Step 4.2: Directory structure**
|
|
|
|
```
|
|
build/
|
|
icons/
|
|
16x16.png
|
|
24x24.png
|
|
32x32.png
|
|
48x48.png
|
|
64x64.png
|
|
128x128.png
|
|
256x256.png
|
|
512x512.png
|
|
1024x1024.png
|
|
```
|
|
|
|
### Phase 5: Protocol Handler Registration
|
|
|
|
For `nodegex://` URLs to work:
|
|
|
|
**Step 5.1: Desktop file configuration**
|
|
|
|
The `mimeTypes` config in package.json creates the association. Additionally, update the `protocols` config:
|
|
|
|
```json
|
|
{
|
|
"build": {
|
|
"protocols": {
|
|
"name": "nodegex",
|
|
"schemes": ["nodegex"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Step 5.2: Manual registration (if needed)**
|
|
|
|
```bash
|
|
# For AppImage users who need manual registration
|
|
xdg-mime default nodegex.desktop x-scheme-handler/nodegex
|
|
```
|
|
|
|
### Phase 6: Build Script
|
|
|
|
**Step 6.1: Create Linux build script**
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# scripts/build-linux.sh
|
|
|
|
set -e
|
|
|
|
# Build for x64 (most common)
|
|
# ARM64 support would require additional setup for native modules
|
|
|
|
echo "Building Linux targets..."
|
|
|
|
# AppImage
|
|
npx electron-builder --linux AppImage --x64
|
|
|
|
# Debian package
|
|
npx electron-builder --linux deb --x64
|
|
|
|
echo "Build complete!"
|
|
echo ""
|
|
echo "Outputs:"
|
|
ls -la dist/*.AppImage dist/*.deb 2>/dev/null || echo "No artifacts found"
|
|
```
|
|
|
|
**Step 6.2: Add to package.json**
|
|
|
|
```json
|
|
{
|
|
"scripts": {
|
|
"build:linux": "./scripts/build-linux.sh",
|
|
"build:linux:appimage": "electron-builder --linux AppImage --x64",
|
|
"build:linux:deb": "electron-builder --linux deb --x64"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Phase 7: Testing
|
|
|
|
**Step 7.1: Test on fresh Ubuntu VM**
|
|
|
|
```bash
|
|
# Ubuntu 22.04 LTS
|
|
sudo apt update
|
|
sudo apt install -y libfuse2 # Required for AppImage
|
|
|
|
chmod +x Nodegex-1.2.0-x64.AppImage
|
|
./Nodegex-1.2.0-x64.AppImage
|
|
```
|
|
|
|
**Step 7.2: Test .deb installation**
|
|
|
|
```bash
|
|
sudo dpkg -i Nodegex-1.2.0-x64.deb
|
|
# If dependencies missing:
|
|
sudo apt-get install -f
|
|
|
|
# Launch
|
|
nodegex
|
|
```
|
|
|
|
**Step 7.3: Test protocol handler**
|
|
|
|
```bash
|
|
xdg-open "nodegex://test"
|
|
```
|
|
|
|
**Step 7.4: Verify auto-update (AppImage only)**
|
|
|
|
1. Install older version
|
|
2. Create GitHub Release with newer version
|
|
3. Wait for update notification
|
|
4. Click "Restart"
|
|
5. Verify new version launches
|
|
|
|
## Known Issues & Workarounds
|
|
|
|
### AppImage FUSE dependency
|
|
|
|
Ubuntu 22.04+ doesn't include FUSE by default:
|
|
|
|
```bash
|
|
# Users need to install:
|
|
sudo apt install libfuse2
|
|
```
|
|
|
|
Document this in release notes.
|
|
|
|
### Wayland compatibility
|
|
|
|
Some Electron features behave differently on Wayland vs X11:
|
|
|
|
```bash
|
|
# Force X11 if issues occur
|
|
GDK_BACKEND=x11 ./Nodegex.AppImage
|
|
```
|
|
|
|
### Sandbox issues on some distributions
|
|
|
|
If sandbox errors occur:
|
|
|
|
```bash
|
|
# Disable sandbox (less secure but works)
|
|
./Nodegex.AppImage --no-sandbox
|
|
```
|
|
|
|
Or fix system-wide:
|
|
```bash
|
|
sudo sysctl -w kernel.unprivileged_userns_clone=1
|
|
```
|
|
|
|
## Files to Modify
|
|
|
|
| File | Changes |
|
|
|------|---------|
|
|
| `packages/noodl-editor/package.json` | Add Linux targets, icons, desktop config |
|
|
| `packages/noodl-editor/src/main/src/autoupdater.js` | Enable for AppImage |
|
|
| `packages/noodl-editor/build/icons/` | Add PNG icon set |
|
|
| `scripts/build-linux.sh` | Create build script |
|
|
|
|
## Success Criteria
|
|
|
|
1. ✅ AppImage runs on fresh Ubuntu 22.04 LTS
|
|
2. ✅ AppImage runs on fresh Ubuntu 24.04 LTS
|
|
3. ✅ .deb installs without manual dependency resolution
|
|
4. ✅ Auto-update works for AppImage distribution
|
|
5. ✅ `nodegex://` protocol handler works
|
|
6. ✅ Desktop integration (icon, menu entry) works
|
|
|
|
## Distribution Channels
|
|
|
|
### GitHub Releases
|
|
|
|
Both AppImage and .deb uploaded to releases.
|
|
|
|
### Optional: Snapcraft
|
|
|
|
```yaml
|
|
# snap/snapcraft.yaml (future enhancement)
|
|
name: nodegex
|
|
base: core22
|
|
version: '1.2.0'
|
|
summary: Visual low-code React development platform
|
|
confinement: classic
|
|
```
|
|
|
|
### Optional: Flathub
|
|
|
|
Flatpak provides another universal format but requires more setup and maintenance.
|
|
|
|
## ARM64 Consideration
|
|
|
|
ARM64 Linux (Raspberry Pi, etc.) would require:
|
|
- Cross-compilation setup
|
|
- ARM64 dugite binaries
|
|
- ARM64 desktop-trampoline build
|
|
|
|
This is out of scope for initial release but could be added later.
|