OpenNoodl/dev-docs/tasks/phase-8-distribution/TASK-7.4-linux-distribution.md

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

{
  "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:

# 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

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

# 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

{
  "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:

if (process.platform === 'linux') {
  return; // Currently disabled
}

We need to enable it for AppImage:

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

# 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:

{
  "build": {
    "protocols": {
      "name": "nodegex",
      "schemes": ["nodegex"]
    }
  }
}

Step 5.2: Manual registration (if needed)

# 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

#!/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

{
  "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

# 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

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

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:

# Users need to install:
sudo apt install libfuse2

Document this in release notes.

Wayland compatibility

Some Electron features behave differently on Wayland vs X11:

# Force X11 if issues occur
GDK_BACKEND=x11 ./Nodegex.AppImage

Sandbox issues on some distributions

If sandbox errors occur:

# Disable sandbox (less secure but works)
./Nodegex.AppImage --no-sandbox

Or fix system-wide:

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

# 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.