Advanced Documentation

Wizard Prompt

When you run npm run dev, you'll see:

🔧 Linux Optimizer WebUI - Setup Wizard

Choose your operating mode:

1) Sudoers Mode
   - Configure sudoers file once
   - Run as regular user with limited sudo scope
   - Password prompts for each operation

2) Sudo Run Mode
   - Run directly with 'sudo'
   - Full root access
   - Will auto-restart with sudo

Enter your choice (1 or 2):

Mode 1: Sudoers Mode (Recommended)

Select option 1 to configure the sudoers file. The app will:

1. Show you a setup script that configures sudoers for Linuxify
2. Run the script automatically (or you can run it manually)
3. Create backups of your original sudoers file
4. Validate the new sudoers configuration

Advantages:

• ✅ Most secure - limited sudo scope
• ✅ No password prompts (after configuration)
• ✅ Runs as regular user (safer)
• ✅ Better for multi-user systems

Mode 2: Sudo Run Mode (Simplest Setup)

Select option 2 to run directly with sudo. The app will:

1. Automatically restart itself with sudo
2. Show your sudo password prompt
3. Run with full root access

Advantages:

• ✅ Simplest setup - no configuration needed
• ✅ Automatic - no manual setup steps
• ✅ Full root access for all operations
• ✅ No password prompts during operation

Disadvantages:

• ⚠️ Runs as root (less secure)
• ⚠️ Security warning displayed in UI
• ⚠️ Not recommended for production

Troubleshooting: If you have Node.js installed via NVM, Homebrew, or other version managers:

1. Option 1 - Use the bash wrapper: ./bin/linuxify.sh
2. Option 2 - Explicit PATH: sudo PATH=$PATH npm run dev
3. Option 3 - Direct node call: sudo /path/to/node npm run dev

Prerequisites

• Linux OS (Ubuntu 20.04+, Debian 10+, AnduinOS, etc.)
• Node.js 16.0.0 or higher
• npm 7.0.0 or higher
• sudo access (for system operations)

Steps

1. Clone or extract the repository
2. Navigate to directory: cd linuxify
3. Install dependencies: npm install
4. Follow Sudo Setup below (optional but recommended)
5. Start the application: npm run dev

Overview

Linuxify tracks and categorizes ~50+ system services into groups:

• Critical System: systemd, dbus, NetworkManager, gdm, polkit
• Display & Graphics: gdm, gnome-shell, wayland
• Hardware: thermald, power-profiles-daemon
• Network: avahi-daemon, bluetooth, ModemManager
• Printing: cups, cups-browsed, sane
• Desktop: gnome-software, gnome-keyring, flatpak
• Background: unattended-upgrades, fwupd, packagekit
• Media: pipewire, pulseaudio

Critical Services (Protected)

Cannot be disabled via UI:

• systemd, systemd-journald, dbus, NetworkManager
• gdm, accounts-daemon, polkit
• thermald, udisks, upower
• Any service matching critical patterns

🔒 These are marked with red "CRITICAL" badge and cannot be toggled.

Safe to Disable

Service	Effect
avahi-daemon	Disables mDNS service discovery
bluetooth	Disables Bluetooth support
cups*	Disables printing
ModemManager	Disables mobile broadband

UI Extensions (Performance Impact)

Heavy extensions that affect system performance:

• blur-my-shell - Blur effects (high CPU)
• dash-to-panel - Panel customization
• arcmenu - Custom app menu
• tiling-assistant - Window tiling
• openweather-extension - Weather widget
• mediacontrols - Media playback controls
• clipboard-indicator - Clipboard history

Other Extensions (System)

System-level extensions:

• customize-ibus - Input method customization
• ubuntu-appindicators - App indicator support
• user-theme - Theme customization
• ding - Desktop icons (file manager)

Recommended

System Info

GET /api/system

Response:
{
  "uptime": "2 weeks, 3 days, 5 hours",
  "load": "0.45",
  "memory": "2.1 / 15G",
  "cpu": "Intel Core i5",
  "distro": "AnduinOS 1.3.2",
  "disk": {
    "total": "109G",
    "used": "39G",
    "available": "65G",
    "usePercent": "38%"
  }
}

Toggle Service

POST /api/service/:name

Body:
{ "action": "disable" }  // or "enable"

Response:
{ "success": true }

Toggle Extension

POST /api/extension/:name

Body:
{ "action": "disable" }  // or "enable"

Response:
{ "success": true }

Run Cleanup

POST /api/cleanup/:actionId

IDs: apt-clean, apt-autoremove, thumbnails, trash,
     npm-cache, yarn-cache, pip-cache, flatpak-cache,
     journal-clean, old-kernels

Response:
{ "success": true }

sudo: no password provided

Solution: Complete the Sudo Setup section above with visudo configuration.

Port 3000 already in use

Solution: Kill existing process or change PORT in server.js

fuser -k 3000/tcp

Extensions not showing

Solution: Refresh browser cache. Some extensions install in system directories.

Disk cleanup not freeing space

Solution: Run one task at a time. Some services may lock files temporarily.

Cannot disable service

Solution: Service is marked as critical. Check the Services tab for which are safe to disable.

Setup Wizard Not Showing

Solution: Run npm run dev to display the wizard again.

Sudo Password Prompt Issues (Mode 1)

If you're still getting password prompts in Sudoers Mode, verify the sudoers configuration:

sudo visudo -c

And check that your user is in the sudo group:

groups $USER

Node Not Found When Using Sudo (Mode 2)

If you see "node: command not found" errors:

1. Try the bash wrapper: ./bin/linuxify.sh
2. Or use explicit PATH: sudo PATH=$PATH npm run dev
3. Or find your node path: which node then sudo /path/to/node npm run dev

Sudoers Mode (Recommended)

• ✅ Runs as regular user
• ✅ Limited sudo scope to specific commands
• ✅ Audit trail in sudoers file
• ✅ Best for multi-user systems
• ✅ Original sudoers backed up automatically

Use Sudoers Mode in production environments.

Sudo Run Mode

• ⚠️ Runs with full root access
• ⚠️ No command restrictions
• ⚠️ Security warning banner displayed
• ⚠️ Best for development/testing only

Additional Security Features

• Critical Services Protection: Cannot be disabled via UI
• Sudoers Validation: Automatic syntax validation during setup
• Backup Creation: Original sudoers backed up to /etc/sudoers.bak
• Limited Commands: Only specific system commands are allowed