From 27a6ee510166c78ba36e972d00dacd4fde36afe7 Mon Sep 17 00:00:00 2001
From: Flamur Veliqi <support@weektab.org>
Date: Sun, 7 Jun 2026 14:29:00 +0000
Subject: [PATCH] Update README.md

---
 README.md | 265 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 264 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 3e9393a..c21607c 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,265 @@
-# xampp-gui
+# XAMPP Control Panel
 
+A web-based GUI to control XAMPP on Linux — start, stop, restart, reload and check the status of Apache, MySQL and FTP with a single click.
+
+---
+
+## Requirements
+
+- Linux (Debian / Ubuntu / Mint or similar)
+- XAMPP installed at `/opt/lampp/`
+- Python 3 (`python3 --version`)
+- A modern browser (Firefox, Chrome, etc.)
+
+---
+
+## Folder structure
+
+Place all files inside `~/xampp-gui/`:
+
+```
+~/xampp-gui/
+├── index.html            ← Web UI
+├── xampp-backend.py      ← Python backend (port 5050)
+├── http-server.py        ← HTTP server (port 8080)
+├── xampp-gui.sh          ← Launcher script
+└── README.md
+```
+
+Create the folder:
+
+```bash
+mkdir -p ~/xampp-gui
+```
+
+---
+
+## Setup
+
+### 1. Make the launcher executable
+
+```bash
+chmod +x ~/xampp-gui/xampp-gui.sh
+```
+
+### 2. Optional: passwordless sudo for XAMPP
+
+The backend runs XAMPP commands via `sudo`. To avoid repeated password prompts, add a sudoers rule:
+
+```bash
+sudo visudo
+```
+
+Add at the end (replace `yourusername`):
+
+```
+yourusername ALL=(ALL) NOPASSWD: /opt/lampp/*
+yourusername ALL=(ALL) NOPASSWD: /opt/lampp/bin/*
+```
+
+Save: `Ctrl+O` → `Enter` → `Ctrl+X`
+
+If you skip this step, the launcher will ask for your password once via `sudo -v` at startup, which is also fine.
+
+---
+
+## Launch
+
+```bash
+bash ~/xampp-gui/xampp-gui.sh
+```
+
+This will:
+
+1. Kill any old processes on ports 5050 and 8080
+2. Ask for your sudo password once (`sudo -v`)
+3. Start the Python backend on port **5050**
+4. Start a local HTTP server on port **8080**
+5. Open the browser automatically at `http://localhost:8080/`
+
+> **Important:** Always open the UI via `http://localhost:8080/`.
+> Do **not** open `index.html` by double-clicking — the browser will block backend requests from `file://` pages.
+
+---
+
+## Manual start (two terminals)
+
+**Terminal 1 – Backend:**
+
+```bash
+python3 ~/xampp-gui/xampp-backend.py
+```
+
+**Terminal 2 – HTTP server:**
+
+```bash
+python3 ~/xampp-gui/http-server.py
+```
+
+Then open: `http://localhost:8080/`
+
+---
+
+## Port overview
+
+| Port | Service |
+|------|---------|
+| 5050 | Python backend (XAMPP commands) |
+| 8080 | HTTP server (Web UI) |
+| 80   | Apache (XAMPP) |
+| 3306 | MySQL (XAMPP) |
+| 21   | FTP / ProFTPD (XAMPP) |
+
+---
+
+## Troubleshooting
+
+**Backend not reachable:**
+
+```bash
+lsof -i :5050
+kill -9 $(lsof -t -i :5050) 2>/dev/null
+python3 ~/xampp-gui/xampp-backend.py &
+```
+
+**Command hangs / timeout:**
+
+```bash
+sudo -v
+bash ~/xampp-gui/xampp-gui.sh
+```
+
+**Port 8080 already in use:**
+
+```bash
+kill -9 $(lsof -t -i :8080) 2>/dev/null
+python3 ~/xampp-gui/http-server.py &
+```
+
+---
+
+## Desktop launcher (.desktop file)
+
+To add XAMPP Control Panel to your application menu or desktop:
+
+```bash
+nano ~/.local/share/applications/xampp-control.desktop
+```
+
+Paste (replace `yourusername`):
+
+```ini
+[Desktop Entry]
+Version=1.0
+Type=Application
+Name=XAMPP Control Panel
+Comment=XAMPP Web GUI starten
+Exec=bash -c "cd /home/yourusername/xampp-gui && bash xampp-gui.sh"
+Icon=/opt/lampp/htdocs/favicon.ico
+Terminal=true
+StartupNotify=false
+Categories=Development;WebDevelopment;
+```
+
+Then make it executable and refresh the application menu:
+
+```bash
+chmod +x ~/.local/share/applications/xampp-control.desktop
+update-desktop-database ~/.local/share/applications/
+```
+
+> **Note:** `Terminal=true` is required — the launcher asks for your sudo password once on startup.
+
+---
+
+## Desktop app (Electron)
+
+You can optionally package the Web UI as a native desktop app using Electron.
+
+### Install Node.js and Electron
+
+```bash
+sudo apt install nodejs npm -y
+```
+
+### Create the app folder
+
+```bash
+mkdir -p ~/xampp-gui-app
+cd ~/xampp-gui-app
+npm init -y
+npm install electron --save-dev
+```
+
+### Create `main.js`
+
+```js
+const { app, BrowserWindow } = require('electron');
+const { spawn } = require('child_process');
+const path = require('path');
+const os = require('os');
+
+let win, backend, server;
+
+function startServices() {
+  const guiDir = path.join(os.homedir(), 'xampp-gui');
+  backend = spawn('python3', [path.join(guiDir, 'xampp-backend.py')], { stdio: 'ignore' });
+  server  = spawn('python3', [path.join(guiDir, 'http-server.py')], { stdio: 'ignore' });
+}
+
+function createWindow() {
+  win = new BrowserWindow({
+    width: 1200,
+    height: 800,
+    autoHideMenuBar: true,
+    title: 'XAMPP Control Panel'
+  });
+  setTimeout(() => win.loadURL('http://localhost:8080/index.html'), 1500);
+}
+
+app.whenReady().then(() => { startServices(); createWindow(); });
+
+app.on('window-all-closed', () => {
+  if (backend) backend.kill();
+  if (server)  server.kill();
+  app.quit();
+});
+```
+
+### Update `package.json`
+
+```json
+{
+  "name": "xampp-control-panel",
+  "version": "1.0.0",
+  "main": "main.js",
+  "scripts": {
+    "start": "electron ."
+  },
+  "devDependencies": {
+    "electron": "^latest"
+  }
+}
+```
+
+### Run the desktop app
+
+```bash
+cd ~/xampp-gui-app
+npm start
+```
+
+For the Electron variant, the `.desktop` file looks like this:
+
+```ini
+[Desktop Entry]
+Version=1.0
+Type=Application
+Name=XAMPP Control Panel
+Comment=XAMPP Web GUI starten
+Exec=bash -c "cd /home/yourusername/xampp-gui-app && npm start"
+Icon=/opt/lampp/htdocs/favicon.ico
+Terminal=false
+StartupNotify=false
+Categories=Development;WebDevelopment;
+```
\ No newline at end of file