mirror of
https://github.com/The-Low-Code-Foundation/OpenNoodl.git
synced 2026-01-11 23:02:56 +01:00
Refactored dev-docs folder after multiple additions to organise correctly
This commit is contained in:
Richard Osborne
@@ -0,0 +1,386 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user