Refactor dashboard widget drag-and-drop functionality and enhance palette interactions

- Removed drag handle from plugin cards in the dashboard.
- Updated CSS for dragging states in the widget palette.
- Enhanced the editor.js to support new widget addition from the palette with auto-save functionality.
- Implemented loading state for newly added widgets and improved rendering logic.
- Added success toast notifications for user feedback on widget addition.
- Refactored palette.js to initialize Sortable.js for the widget palette and handle drag events.
- Removed legacy drag-and-drop functionality from the plugins page, transitioning to sidebar edit mode for plugin reordering.

Author: sarg3nt

README.md

@@ -17,6 +17,17 @@ Gearbox is a general-purpose monitoring and management platform with a plugin-ba
 
 **IMPORTANT:** Gearbox is NOT an HAProxy-specific tool. It is a universal monitoring platform. HAProxy monitoring is just one plugin among many.
 
+## 🚀 Getting Started
+
+**New to Gearbox?** Follow our comprehensive [Getting Started Guide](docs/GETTING_STARTED.md) for step-by-step instructions on:
+
+- Installing the Gearbox dashboard and agent
+- Generating and configuring API keys
+- Adding your first monitored server
+- Enabling plugins and creating dashboards
+
+The guide includes detailed examples, troubleshooting tips, and best practices for production deployments.
+
 ## Quick Start
 
 ### Prerequisites

TASKS.md

@@ -125,26 +125,51 @@ Framework = Shared services and building blocks (graphs, tables, panels, cards,
 - Fetches widgets dynamically from `/api/dashboards/widgets` endpoint
 - Responsive design with dark mode support
 
-#### Task 3: Drag-and-Drop from Palette
+#### Task 3: Drag-and-Drop from Palette ✅
 
-- [ ] Extend `gearbox/static/js/dashboard/editor.js` drag-drop functionality
-- [ ] Use SortableJS `group` option to enable cross-container dragging
-- [ ] On drop: generate widget ID, create instance, add to dashboard, save YAML
-- [ ] Show loading state while widget content loads via HTMX
+- [x] Extend `gearbox/static/js/dashboard/editor.js` drag-drop functionality
+- [x] Use SortableJS `group` option to enable cross-container dragging
+- [x] On drop: generate widget ID, create instance, add to dashboard, save YAML
+- [x] Show loading state while widget content loads via HTMX
 
-#### Task 4: Navigation Updates
+**Implementation Details:**
 
-- [ ] Create dynamic plugin navigation
-- [ ] Show plugin menu items only when enabled for server
-- [ ] Ensure plugin menu items update when plugins are enabled/disabled
+- Configured SortableJS with `group` option for cross-container dragging between palette and grid
+- Palette widgets use `pull: 'clone'` to allow dragging without removing from palette
+- Grid accepts drops from palette via `put: ['widget-palette']`
+- `onAdd` handler creates new widget instances with unique IDs when dropped
+- Auto-saves dashboard after widget drop with silent save (no page reload)
+- Displays loading state during widget creation, then shows placeholder content
+- Widget position is automatically calculated based on drop index
+- Edit controls (drag handle, delete button) are injected after widget creation
+- Success toast notification confirms widget addition
+- Built successfully with `make templ-generate && make build`
+
+#### Task 4: Navigation Updates ✅
+
+- [x] Create dynamic plugin navigation
+- [x] Show plugin menu items only when enabled for server
+- [x] Ensure plugin menu items update when plugins are enabled/disabled
+- [x] Left hand nav items can be rearranged by clicking edit icon that is next to the toggle sidebar icon
+- [x] When in edit mode user can drag a menu item up or down and other nav items flow around it
+- [x] Edit icon becomes save icon while in edit mode
+- [x] When a plugin is enabled it generates its default "dashboard" interface yaml file if it does not already exist.  Each plugin's default dashboard has a default name and icon as designed by plugin developer.  When plugins is enabled it is added to the nav bar
+- [x] The rearrangement of left hand nav items will be removed from the plugin screen, all nav rearrangement is now in the nav bar only.
 
-#### Task 5: Left Hand Navigation bar Updates
+**Implementation Details:**
 
-- [ ] Items can be rearranged by clicking edit icon that is next to the toggle sidebar icon
-- [ ] When in edit mode user can drag a menu item up or down and other nav items flow around it
-- [ ] Edit icon becomes save icon
-- [ ] When a plugin is enabled it generates its default "dashboard" interface yaml file if it does not already exist.  Each plugin's default dashboard has a default name and icon as designed by plugin developer.  When plugins is enabled it is added to the nav bar
-- [ ] The rearrangement of left hand nav items will be removed from the plugin screen, all nav rearrangement is now in the nav bar only.
+- Added edit mode toggle button next to sidebar collapse button in [base.templ](gearbox/internal/framework/templates/layouts/base.templ:1105-1129)
+- Edit icon switches to save/checkmark icon when in edit mode
+- Created `SidebarLinkDraggable` and `SidebarLinkDraggableWithBadge` templ components with data attributes and drag handles
+- Implemented `toggleSidebarEditMode()` JavaScript function for managing edit state
+- Used SortableJS for drag-and-drop reordering of navigation items
+- Drag handles visible only in edit mode, links disabled during editing
+- `saveSidebarOrder()` POSTs new order to `/api/integrations/sort-order` endpoint
+- Removed drag handle from plugin cards in [plugins.templ](gearbox/internal/framework/templates/pages/plugins.templ)
+- Disabled drag-and-drop in [plugins-page.js](gearbox/static/js/plugins/plugins-page.js) with explanatory comments
+- Dynamic navigation already working via `OrderedIntegrationLinks()` and middleware
+- Plugin dashboards auto-generate when enabled (completed in Task 1)
+- Built successfully with `make templ-generate && make build`
 
 **Testing Checklist:**
 
@@ -186,20 +211,3 @@ Framework = Shared services and building blocks (graphs, tables, panels, cards,
 - **Agent API Docs:** [gearbox-agent/docs/](gearbox-agent/docs/)
 - **Plugin Architecture:** [docs/plugins.md](docs/plugins.md)
 - **Development Guide:** [gearbox/docs/development.md](gearbox/docs/development.md)
-
----
-
-## Fresh Start
-
-Code to run for a fresh start (deletes local database and starts dev server):
-
-```bash
-# from the gearbox directory
-cd ../gearbox-agent
-make deploy
-cd -
-rm -f data/haproxy-monitor.db
-rm -rf data/dashboards
-make dev-local
-```
-

docs/GETTING_STARTED.md

@@ -0,0 +1,216 @@
+# Getting Started with Gearbox
+
+Welcome to Gearbox! This guide will walk you through setting up your first monitored server or workstation (we call these "Boxes").
+
+## Overview
+
+Gearbox is a plugin-based server monitoring and management platform that consists of two components:
+
+- **Gearbox Dashboard** - Web interface for monitoring multiple servers (port 3000)
+- **Gearbox Agent** - Lightweight service installed on each Box you want to monitor (port 8405)
+
+## Prerequisites
+
+- A Linux server or workstation to monitor (the "Box")
+- Go 1.21+ installed on the Box (for building the agent)
+- Network connectivity between the dashboard and the Box on port 8405
+
+## Quick Start
+
+### Step 1: Install Gearbox Dashboard
+
+The dashboard is where you'll view and manage all your monitored Boxes.
+
+```bash
+# Clone the repository
+git clone https://github.com/sarg3nt/gearbox.git
+cd gearbox/gearbox
+
+# Build the dashboard
+make build
+
+# Run the dashboard
+./bin/gearbox
+```
+
+The dashboard will be available at `http://localhost:3000`
+
+### Step 2: Install Gearbox Agent on Your Box
+
+On the server or workstation you want to monitor:
+
+```bash
+# Clone the repository
+git clone https://github.com/sarg3nt/gearbox.git
+cd gearbox/gearbox-agent
+
+# Build the agent
+make build
+
+# The agent binary will be in ./bin/gearbox-agent
+```
+
+### Step 3: Generate an API Key
+
+1. Open the Gearbox dashboard at `http://localhost:3000`
+2. Navigate to **Settings > Servers** and click **Add Server**
+3. Click the **Generate API Key** button
+4. Copy the generated API key to your clipboard
+5. **Important:** Save this key somewhere safe - you won't be able to see it again!
+
+### Step 4: Configure the Agent
+
+Create a configuration file or set environment variables on your Box:
+
+#### Option A: Environment Variables (Recommended)
+
+```bash
+export GEARBOX_API_KEY="your-generated-api-key-here"
+export GEARBOX_PORT="8405"  # Optional, defaults to 8405
+```
+
+Add these to your shell profile (`~/.bashrc`, `~/.zshrc`) or create a systemd service file to make them persistent.
+
+#### Option B: Configuration File
+
+Create `/etc/gearbox-agent/config.yaml`:
+
+```yaml
+api_key: "your-generated-api-key-here"
+port: 8405
+```
+
+### Step 5: Start the Agent
+
+```bash
+# Start the agent
+cd gearbox-agent
+./bin/gearbox-agent
+```
+
+The agent will start on port 8405 and begin collecting system metrics.
+
+### Step 6: Add the Box to Your Dashboard
+
+1. Return to the Gearbox dashboard
+2. In the **Add Server** form, fill in:
+   - **Server Name**: A friendly name (e.g., "Production Web Server")
+   - **Server ID**: A unique identifier (e.g., "web-prod-01")
+   - **Agent URL**: The URL to your agent (e.g., `http://192.168.1.100:8405`)
+   - **API Key**: Paste the API key you generated earlier
+3. Click **Test Connection** to verify connectivity
+4. Click **Add Server** to save
+
+### Step 7: Enable Plugins
+
+After adding your first Box:
+
+1. Navigate to **Settings > Plugins**
+2. Enable the plugins you want to use:
+   - **HAProxy** - HAProxy monitoring and statistics
+   - **Metrics** - System metrics visualization
+   - **Services** - Service management and monitoring
+   - **Certificates** - TLS certificate tracking
+   - **Logs** - Log aggregation and viewing
+   - **Traffic** - Traffic analysis and visualization
+   - **Alerts** - Alert management
+   - **OS Updates** - OS package updates
+
+When you enable a plugin, its default dashboard will be automatically created and added to the navigation.
+
+## Running as a System Service
+
+### Systemd Service (Linux)
+
+Create `/etc/systemd/system/gearbox-agent.service`:
+
+```ini
+[Unit]
+Description=Gearbox Agent - Server Monitoring
+After=network.target
+
+[Service]
+Type=simple
+User=gearbox
+WorkingDirectory=/opt/gearbox-agent
+Environment="GEARBOX_API_KEY=your-api-key-here"
+Environment="GEARBOX_PORT=8405"
+ExecStart=/opt/gearbox-agent/bin/gearbox-agent
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start the service:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable gearbox-agent
+sudo systemctl start gearbox-agent
+sudo systemctl status gearbox-agent
+```
+
+## Auto-Discovery
+
+Gearbox Agent automatically discovers services running on your Box:
+
+- **HAProxy** - Detects running HAProxy instances and collects stats
+- **Docker** - Discovers Docker containers and images
+- **System Services** - Monitors systemd services
+
+No manual configuration required! Just enable the relevant plugins in the dashboard.
+
+## Security Considerations
+
+1. **API Key Security**: Treat your API key like a password. Never commit it to version control.
+2. **Network Security**: Use a firewall to restrict access to port 8405 to only your dashboard server.
+3. **HTTPS**: In production, run both the dashboard and agent behind a reverse proxy with HTTPS.
+4. **Authentication**: The dashboard supports password authentication and WebAuthn. Enable it for production use.
+
+## Troubleshooting
+
+### Agent Won't Start
+
+- Verify the `GEARBOX_API_KEY` environment variable is set
+- Check if port 8405 is available: `sudo netstat -tulpn | grep 8405`
+- Review agent logs for errors
+
+### Connection Test Fails
+
+- Verify the Agent URL is correct and accessible from the dashboard server
+- Check firewall rules on both the dashboard and Box
+- Confirm the API key matches between dashboard and agent
+- Use `curl` to test: `curl http://your-box:8405/health`
+
+### No Data Showing
+
+- Wait 30-60 seconds for the first data collection cycle
+- Verify the plugin is enabled in **Settings > Plugins**
+- Check that the service you're trying to monitor is actually running on the Box
+- Review agent logs for collection errors
+
+## Next Steps
+
+- **Customize Dashboards**: Create custom dashboards with your favorite widgets
+- **Configure Alerts**: Set up alert rules for critical metrics
+- **Enable GitOps**: Configure git sync for dashboard definitions
+- **Add More Boxes**: Repeat the process to monitor additional servers
+
+## Getting Help
+
+- **Documentation**: [GitHub Repository](https://github.com/sarg3nt/gearbox)
+- **Issues**: [Report a Bug](https://github.com/sarg3nt/gearbox/issues)
+- **Architecture**: See [docs/plugins.md](plugins.md) for plugin architecture details
+
+## What's Next?
+
+Now that you have Gearbox running, explore:
+
+1. **Widget System**: Learn how to create custom widgets
+2. **Plugin Development**: Build your own monitoring plugins
+3. **Dashboard Layouts**: Customize dashboard arrangements
+4. **Advanced Configuration**: Explore environment variables and configuration options
+
+Happy monitoring! 📊

gearbox/internal/framework/handler/haproxy_config.go

@@ -50,7 +50,14 @@ func (h *Handler) HAProxyServerNewPage(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	component := pages.HAProxyServerNewPage(user, "")
+	// Fetch existing servers to determine if we should show sidebar
+	servers, err := h.db.GetServers()
+	if err != nil {
+		h.logger.Error("Failed to fetch servers", "error", err)
+		servers = []*database.ServerDB{} // Default to empty to show no-sidebar layout
+	}
+
+	component := pages.HAProxyServerNewPage(user, servers, "")
 	if err := component.Render(r.Context(), w); err != nil {
 		h.logger.Error("Failed to render new server page", "error", err)
 		http.Error(w, "Internal server error", http.StatusInternalServerError)
@@ -479,7 +486,14 @@ func (h *Handler) renderServerFormWithError(w http.ResponseWriter, r *http.Reque
 			http.Error(w, "Internal server error", http.StatusInternalServerError)
 		}
 	} else {
-		component := pages.HAProxyServerNewPage(user, errorMsg)
+		// Fetch existing servers to determine if we should show sidebar
+		servers, err := h.db.GetServers()
+		if err != nil {
+			h.logger.Error("Failed to fetch servers", "error", err)
+			servers = []*database.ServerDB{} // Default to empty to show no-sidebar layout
+		}
+
+		component := pages.HAProxyServerNewPage(user, servers, errorMsg)
 		if err := component.Render(r.Context(), w); err != nil {
 			h.logger.Error("Failed to render form", "error", err)
 			http.Error(w, "Internal server error", http.StatusInternalServerError)