Adding Controller documentation and screnshots.

.idea/misc.xml

@@ -3,5 +3,5 @@
   <component name="Black">
     <option name="sdkName" value="Python 3.11 (wrolpi-help)" />
   </component>
-  <component name="ProjectRootManager" version="2" project-jdk-name="Python 3.11 (wrolpi-help)" project-jdk-type="Python SDK" />
+  <component name="ProjectRootManager" version="2" project-jdk-name="Python 3.14 (wrolpi-help)" project-jdk-type="Python SDK" />
 </project>

.idea/wrolpi-help.iml

@@ -5,7 +5,7 @@
       <excludeFolder url="file://$MODULE_DIR$/.venv" />
       <excludeFolder url="file://$MODULE_DIR$/venv" />
     </content>
-    <orderEntry type="jdk" jdkName="Python 3.11 (wrolpi-help)" jdkType="Python SDK" />
+    <orderEntry type="jdk" jdkName="Python 3.14 (wrolpi-help)" jdkType="Python SDK" />
     <orderEntry type="sourceFolder" forTests="false" />
   </component>
 </module>

docs/controller/dashboard.md

@@ -0,0 +1,103 @@
+# Controller Dashboard
+
+The Controller provides a standalone web dashboard that works independently from the main WROLPi
+application. This ensures you always have access to critical system information and controls.
+
+## Accessing the Dashboard
+
+The dashboard is available at:
+
+```
+http://<your-wrolpi-ip>:8087
+```
+
+## When to Use the Dashboard
+
+The standalone dashboard is useful when:
+
+- The main WROLPi app is down or unresponsive
+- WROLPi is upgrading
+- You need quick access to system status
+- You're troubleshooting service issues
+
+## Dashboard Sections
+
+### System Status Cards
+
+The top of the dashboard displays real-time system metrics:
+
+| Metric      | Description                                  |
+|-------------|----------------------------------------------|
+| **CPU**     | Current CPU usage percentage and temperature |
+| **Memory**  | RAM usage (used/total) and percentage        |
+| **Load**    | 1-minute system load average                 |
+| **Storage** | Primary drive usage and free space           |
+| **IO Wait** | Percentage of time CPU waits for disk I/O    |
+| **Uptime**  | Time since last boot                         |
+
+![Dashboard status cards](dashboard-status-cards.png)
+
+### System Actions
+
+Quick action buttons for system-wide operations:
+
+- **Restart All Services** - Restarts all WROLPi services (Controller restarts last)
+- **Reboot** - Reboots the entire system
+- **Shutdown** - Shuts down the system (native mode only)
+
+### Services Table
+
+Lists all WROLPi services with their current status:
+
+- Service name and port number
+- Status indicator (running/stopped/failed)
+- Control buttons (Start/Stop/Restart)
+- Log viewer button
+- Link to service UI (if applicable)
+- Boot toggle (enable/disable at startup)
+
+_The following screenshot is from a healthy WROLPi._
+
+![Dashboard services table](dashboard-services-table.png)
+
+### Disk Management
+
+Shows detected drives and partitions:
+
+- Device name and size
+- Filesystem type and label
+- Mount/unmount controls
+- Persistent mount toggle
+
+### Drive Health (SMART)
+
+Displays health information for connected drives:
+
+- Overall assessment (PASS/FAIL/WARN)
+- Temperature
+- Power-on hours
+- Sector health
+
+## Fallback Mode
+
+When the main WROLPi API is unavailable, the dashboard enters "fallback mode":
+
+- A notice appears indicating the main app is down
+- The dashboard continues to function normally
+- Once the main app recovers, you're automatically redirected
+
+## Upgrade Mode
+
+During system upgrades:
+
+- The dashboard shows upgrade status
+- An elapsed time counter tracks upgrade duration
+- Service logs are available for monitoring progress
+- The system automatically returns to normal once the upgrade completes
+
+![dashboard-upgrade-banner.png](dashboard-upgrade-banner.png)
+
+## Auto-Refresh
+
+The dashboard automatically refreshes system metrics every few seconds. The refresh interval adapts
+based on system load to minimize overhead.

docs/controller/disks.md

@@ -0,0 +1,86 @@
+# Disk Management
+
+The Controller provides tools for mounting and managing external drives and storage devices.
+
+## Supported Filesystems
+
+The following filesystem types can be mounted:
+
+- **ext4** - Linux native filesystem (recommended)
+- **btrfs** - Linux filesystem with advanced features
+- **vfat** - FAT32, compatible with Windows/Mac
+- **exfat** - Extended FAT, good for large files and cross-platform use
+
+## Viewing Disks
+
+The disk management section shows all detected block devices and partitions:
+
+| Column      | Description                             |
+|-------------|-----------------------------------------|
+| Device      | Device path (e.g., /dev/sda1)           |
+| Size        | Partition size                          |
+| Filesystem  | Detected filesystem type                |
+| Label       | Volume label (if set)                   |
+| Mount Point | Where the drive is mounted (if mounted) |
+
+## Mounting a Drive
+
+1. Locate the drive in the disk list
+2. Click the **Mount** button
+3. Optionally specify a custom mount point (must be under `/media`)
+4. The drive will be mounted and accessible
+
+### Default Mount Points
+
+If no mount point is specified, drives are mounted under `/media` using the device name or label.
+
+### Filesystem Permissions
+
+For exfat and vfat filesystems, the Controller automatically sets ownership to the `wrolpi` user
+so files are accessible to WROLPi services.
+
+## Unmounting a Drive
+
+1. Find the mounted drive in the list
+2. Click the **Unmount** button
+3. The drive will be safely unmounted
+
+**Note:** A drive cannot be unmounted if files are in use. Close any applications or processes
+using files on the drive before unmounting.
+
+## Persistent Mounts
+
+Persistent mounts survive system reboots. The Controller manages these through the system's
+fstab configuration.
+
+### Making a Mount Persistent
+
+1. Mount the drive
+2. Enable the **Persistent** toggle for the mount
+3. The mount will be added to fstab and restored on reboot
+
+### Removing a Persistent Mount
+
+1. Disable the **Persistent** toggle
+2. The fstab entry will be removed
+3. The drive will not auto-mount on next boot
+
+## Protected Mount Points
+
+The following system mount points cannot be modified:
+
+- `/` (root filesystem)
+- `/boot`
+- `/boot/firmware`
+
+Attempting to unmount these will be blocked to protect system stability.
+
+## Mount Point Restrictions
+
+For security, mount points are restricted to the `/media` directory. This prevents accidentally
+mounting drives over system directories.
+
+## Docker Mode
+
+In Docker deployments, disk mounting must be handled on the host system. The Controller can
+display disk information but cannot perform mount operations from within a container.

docs/controller/index.md

@@ -0,0 +1,99 @@
+# Controller
+
+The WROLPi Controller is a system management service that provides monitoring, service control, disk
+management, and administrative functions for your WROLPi instance.
+
+## Why the Controller?
+
+The Controller runs independently from the main WROLPi application. This means:
+
+- **System management is always available** - Even if the main app crashes or is upgrading, you can still
+  manage services, mount disks, and monitor system health.
+- **Fallback UI** - When the main React app is unavailable, the Controller provides a standalone dashboard.
+- **Critical operations** - Shutdown, reboot, and service restart are handled by a dedicated service.
+
+## Accessing the Controller
+
+### From the Main App
+
+Navigate to **Admin > Control** in the main WROLPi interface to access Controller features integrated into
+the React UI.
+
+![Controller in Admin tab](controller-admin-tab.png)
+
+### Standalone Dashboard
+
+The Controller has its own standalone web interface available at:
+
+```
+http://<your-wrolpi-ip>:8087
+```
+
+This dashboard works even when the main WROLPi app is down.
+
+### During Upgrades
+
+When WROLPi is upgrading, nginx automatically redirects to the Controller dashboard so you can monitor the
+upgrade progress and system status.
+
+## Features
+
+### [Dashboard](dashboard.md)
+
+The standalone HTML dashboard provides real-time system monitoring:
+
+- CPU usage and temperature
+- Memory utilization
+- Storage space
+- System load and IO wait
+- Uptime
+
+### [Service Management](services.md)
+
+Control all WROLPi services:
+
+- Start, stop, and restart services
+- View service logs
+- Enable or disable services at boot
+
+### [Disk Management](disks.md)
+
+Manage external drives and storage:
+
+- Mount and unmount drives
+- Configure persistent mounts (survive reboots)
+- View disk information (size, filesystem, label)
+
+### [SMART Monitoring](smart.md)
+
+Monitor drive health:
+
+- Drive health assessment (PASS/FAIL/WARN)
+- Temperature monitoring
+- Power-on hours
+- Sector health (reallocated, pending)
+
+### [System Actions](system.md)
+
+Administrative controls:
+
+- Restart all WROLPi services
+- Reboot the system
+- Shutdown the system
+- WiFi hotspot control (Raspberry Pi)
+- CPU throttling/governor control
+
+## Docker vs Native Mode
+
+The Controller operates differently depending on how WROLPi is deployed:
+
+| Feature            | Native (Raspberry Pi) | Docker                 |
+|--------------------|-----------------------|------------------------|
+| Service management | Full (systemd)        | Container control      |
+| Disk mounting      | Full                  | Limited (host-managed) |
+| SMART monitoring   | Full                  | Not available          |
+| Hotspot control    | Full                  | Not available          |
+| CPU throttle       | Full                  | Not available          |
+| Shutdown/Reboot    | Full                  | Not available          |
+
+In Docker mode, disk mounting and hardware-specific features must be managed on the host system.

docs/controller/services.md

@@ -0,0 +1,117 @@
+# Service Management
+
+The Controller allows you to manage all WROLPi services from a single interface.
+
+## Managed Services
+
+The following services are managed by the Controller:
+
+| Service           | Port   | Description                      |
+|-------------------|--------|----------------------------------|
+| wrolpi-controller | 8087   | System management (this service) |
+| wrolpi-api        | 8081   | Backend API server               |
+| wrolpi-app        | 5000   | React frontend application       |
+| wrolpi-help       | 8084   | Documentation server             |
+| wrolpi-kiwix      | 8085   | Offline wiki server (Kiwix)      |
+| renderd           | -      | Map tile rendering               |
+| apache2           | -      | Map tile server                  |
+| postgresql        | -      | Database server                  |
+| nginx             | 80/443 | Web server and reverse proxy     |
+
+Development services (shown only when running):
+
+- wrolpi-api-dev - API in debug mode
+- wrolpi-app-dev - Frontend in development mode
+- wrolpi-upgrade - System upgrade process
+
+## Service Controls
+
+### Starting a Service
+
+Click the **Start** button next to a stopped service to start it. The status will update once the
+service is running.
+
+![Service start button](services-start-button.png)
+
+### Stopping a Service
+
+Click the **Stop** button to stop a running service. Use caution when stopping critical services
+like nginx or postgresql.
+
+![Service stop button](services-stop-button.png)
+
+### Restarting a Service
+
+Click the **Restart** button to stop and start a service. This is useful when a service is
+misbehaving or after configuration changes.
+
+![Service restart button](services-restart-button.png)
+
+### Enabling/Disabling at Boot
+
+Toggle the boot switch to control whether a service starts automatically when the system boots.
+This is only available in native mode (systemd).
+
+![Service boot toggle](services-boot-toggle.png)
+
+## Viewing Service Logs
+
+Click the **Logs** button to view recent log output for a service.
+
+![Service logs button](services-logs-button.png)
+
+### Log Options
+
+- **Lines** - Number of log lines to retrieve (100-5000)
+- **Download** - Save logs as a text file for offline analysis
+
+![Service log options](services-log-options.png)
+
+### Auto-Scroll
+
+When viewing logs, scroll to the bottom to enable auto-refresh. New log entries will appear
+automatically. Scroll up to pause auto-refresh.
+
+## Restart All Services
+
+The "Restart All Services" button restarts all WROLPi services in sequence. The Controller
+restarts itself last to ensure the operation completes.
+
+This is useful after:
+
+- System configuration changes
+- Recovering from errors
+- Applying updates
+
+![Restart all services button](services-restart-all.png)
+
+## Docker Mode
+
+In Docker deployments, the Controller manages Docker containers instead of systemd services:
+
+- Container start/stop/restart is available
+- Boot toggle is not available (managed by Docker Compose)
+- Container names differ from native systemd service names
+
+### Docker Container Architecture
+
+Docker mode uses HTTPS proxy containers to expose services securely:
+
+| Service | Internal Container | HTTPS Proxy  | Port |
+|---------|--------------------|--------------|------|
+| Help    | `help`             | `help_https` | 8086 |
+| Map     | `map`              | `map_https`  | 8084 |
+| Kiwix   | `zim`              | `zim_https`  | 8085 |
+| Archive | -                  | `archive`    | 8083 |
+
+Other containers:
+
+- `api` - Backend API (port 8081)
+- `app` - React frontend
+- `controller` - Controller service (port 8087)
+- `db` - PostgreSQL database (port 5432)
+- `web` - Nginx reverse proxy (port 8443)
+
+*The following screenshot is from a healthy WROLPi running in Docker containers*
+
+![Docker mode services](services-docker-mode.png)

docs/controller/smart.md

@@ -0,0 +1,81 @@
+# SMART Drive Monitoring
+
+SMART (Self-Monitoring, Analysis and Reporting Technology) provides early warning of drive
+failures. The Controller monitors SMART data for all connected drives.
+
+## Drive Health Assessment
+
+Each drive displays an overall health assessment:
+
+| Status   | Meaning                                      |
+|----------|----------------------------------------------|
+| **PASS** | Drive is healthy, no issues detected         |
+| **WARN** | Potential issues detected, monitor closely   |
+| **FAIL** | Drive is failing or has failed, replace soon |
+
+_Image taken from a WROLPi with two external USB disks_
+
+![SMART health assessment](smart-health-assessment.png)
+
+## Monitored Attributes
+
+### Temperature
+
+Current drive temperature in Celsius. High temperatures can indicate:
+
+- Poor ventilation
+- Heavy workload
+- Impending failure
+
+Most drives operate safely below 50°C. Temperatures above 60°C may reduce drive lifespan.
+
+### Power-On Hours
+
+Total hours the drive has been powered on. This helps estimate drive age and remaining lifespan.
+Most drives are rated for 3-5 years of continuous operation (26,000-44,000 hours).
+
+### Reallocated Sector Count
+
+Number of bad sectors that have been remapped to spare sectors. A small number is normal over
+time, but rapid increases indicate drive degradation.
+
+### Pending Sector Count
+
+Sectors waiting to be remapped. These are sectors that had read errors but haven't been
+reallocated yet. Non-zero values warrant monitoring.
+
+## Viewing Detailed SMART Data
+
+Click on a drive's SMART status to view the full SMART attributes table. This includes:
+
+- All SMART attribute values
+- Threshold values
+- Raw values
+- Worst recorded values
+
+![SMART detailed attributes](smart-detailed-attributes.png)
+
+## Drives Without SMART
+
+Some drives don't support SMART monitoring:
+
+- USB flash drives
+- SD cards
+- Some external enclosures that don't pass SMART data
+- Virtual disks
+
+These drives will show "SMART not available" in the status.
+
+## Recommendations
+
+- **Check SMART status regularly** - Weekly checks can catch problems early
+- **Replace WARN drives soon** - Don't wait for failure
+- **Backup immediately on FAIL** - Data loss may be imminent
+- **Monitor temperature** - Ensure adequate cooling
+
+## Docker Mode
+
+SMART monitoring requires direct hardware access and is not available in Docker deployments.
+Monitor drive health from the host system instead.
+
+![SMART not available in Docker mode](smart-docker-mode.png)

docs/controller/system.md

@@ -0,0 +1,135 @@
+# System Actions
+
+The Controller provides administrative controls for system-wide operations.
+
+![System actions overview](system-actions-overview.png)
+
+## Restart All Services
+
+Restarts all WROLPi services in sequence:
+
+1. wrolpi-api
+2. wrolpi-app
+3. wrolpi-help
+4. wrolpi-kiwix
+5. Other services as needed
+6. wrolpi-controller (restarts last)
+
+The Controller restarts itself last to ensure all other services are restarted first.
+
+**Use when:**
+
+- Services are unresponsive
+- After configuration changes
+- To clear stale state
+
+## Reboot System
+
+Reboots the entire WROLPi system. The system will:
+
+1. Stop all services gracefully
+2. Unmount filesystems
+3. Restart the operating system
+4. Boot and start all services
+
+The reboot process takes 1-3 minutes depending on hardware. After reboot, the system will
+be accessible at the same IP address (unless DHCP assigns a new one).
+
+**Use when:**
+
+- System is unstable
+- After system updates
+- Hardware changes require a fresh boot
+
+## Shutdown System
+
+Shuts down the WROLPi system completely. The system will:
+
+1. Stop all services gracefully
+2. Unmount filesystems
+3. Power off
+
+**Note:** Physical access is required to power the system back on.
+
+This feature is only available in native mode, not Docker.
+
+## WiFi Hotspot (Raspberry Pi)
+
+On Raspberry Pi, the Controller can manage a WiFi hotspot for direct device connections.
+
+### Hotspot Status
+
+- **Disconnected** - Hotspot is off
+- **Connected** - Hotspot is active, devices can connect
+- **In Use** - Devices are currently connected
+- **Unavailable** - WiFi hardware not available
+
+### Enabling the Hotspot
+
+1. Click **Enable Hotspot**
+2. The Pi will create a WiFi network
+
+Default hotspot settings:
+
+- **SSID:** WROLPi
+- **Password:** wrolpi hotspot
+- **Device:** wlan0
+
+### Disabling the Hotspot
+
+Click **Disable Hotspot** to turn off the WiFi access point. Connected devices will be
+disconnected.
+
+### When to Use Hotspot
+
+The hotspot is useful for:
+
+- Direct connection when no WiFi network is available
+- Field use without infrastructure
+- Initial setup before configuring WiFi
+
+## CPU Throttling (Raspberry Pi)
+
+Control CPU performance and power consumption on Raspberry Pi.
+
+### Throttle Status
+
+Shows the current CPU governor:
+
+- **ondemand** - Normal operation, scales with demand
+- **powersave** - Reduced speed, lower power consumption
+- **performance** - Maximum speed (not recommended for sustained use)
+
+### Enable Throttle (Powersave)
+
+Switches to powersave mode:
+
+- Reduces CPU frequency
+- Lowers power consumption
+- Reduces heat generation
+- May slow down intensive operations
+
+**Use when:**
+
+- Running on battery power
+- Reducing heat in enclosed spaces
+- Minimizing power draw
+
+### Disable Throttle
+
+Returns to normal operation (ondemand governor):
+
+- CPU scales with workload
+- Full performance available when needed
+- Normal power consumption
+
+## Docker Mode Limitations
+
+The following system actions are not available in Docker deployments:
+
+- Shutdown
+- Reboot
+- WiFi hotspot control
+- CPU throttling
+
+These operations must be performed on the host system.

docs/other/ebooks.md

@@ -5,7 +5,7 @@ may not yet be available.
 
 Epub files are desired as ebooks, though some support for Mobi files is provided. Reasons why WROLPi supports Epub:
 
-* Epub files are simple.  An Epub file is a zip file containing HTML files.
+* Epub files are simple. An Epub file is a zip file containing HTML files.
 * Third-party support for reading Epubs is much more feature-rich.
 * Images are files in the Epub zip.
 * Device supports for Epubs is nearly ubiquitous.
@@ -17,4 +17,4 @@ When indexes for an EPUB are generated, they are searched in the following order
 
 1. Title
 2. Author
-3. eBook contents
+3. eBook contents

docs/system/backup.md

@@ -1,4 +1,5 @@
 # Backup
+
 ## Backup from one WROLPi to another
 
 As of the writing of this tutorial, WROLPi does not have an official way to back up a WROLPi. The current workaround
@@ -51,4 +52,4 @@ EOF
 
 ```shell
 0 4 * * * /bin/bash -l /home/wrolpi/backup_wrolpi.sh
-```
+```

docs/system/external-drives.md

@@ -1,5 +1,12 @@
 # External USB Drive Configuration
 
+For basic disk mounting, the [Controller](../controller/disks.md) provides a web interface to mount
+drives and configure persistent mounts.
+
+The instructions below are for manual configuration or advanced multi-drive setups.
+
+---
+
 WROLPi expects a single USB drive to be mounted at `/media/wrolpi`. However, multiple drives are supported. WROLPi
 uses special directories to know where to place downloaded files. The config special directories cannot be changed
 and WROLPi will always look for it at `/media/wrolpi/config`

docs/system/getting-help.md

@@ -1,4 +1,5 @@
 # Getting Help
+
 ## Online
 
 Help can be found online at these places:
@@ -103,4 +104,4 @@ The `wrolpi` database contains the tables and indexes which allow you to search
 provided which will delete and re-create this database.  **Warning you will need to refresh your files!**  Run it if the
 repair script above fails:
 
-`/opt/wrolpi/scripts/reset_api_db.sh`
+`/opt/wrolpi/scripts/reset_api_db.sh`

docs/system/logs.md

@@ -1,7 +1,17 @@
 # Logs
 
+Service logs can be viewed through the [Controller](../controller/services.md#viewing-service-logs)
+web interface, or via command line using `journalctl`.
+
+## Using the Controller
+
+Click the **Logs** button next to any service in the Controller to view its recent log output.
+See [Viewing Service Logs](../controller/services.md#viewing-service-logs) for details.
+
+## Command Line
+
 The following is a simple overview to view the logs of the [WROLPi Services](index.md#services). WROLPi logs are
-gathered by `systemd`.  Logs are viewed using `journalctl`.
+gathered by `systemd`. Logs are viewed using `journalctl`.
 
 You can watch all the logs on your WROLPi:
 
@@ -21,9 +31,9 @@ To view logs only from the most recent boot:
 journalctl -f -b
 ```
 
-The above commands use `-f` (follow) which will display logs as soon as they are created.  You can view older logs by
-removing `-f` from the command, but you will need to use your keyboard to navigate the logs.  Use `up`, `down`,
-`page-up` and `page-down` keys.  You can also use `g` to navigate to the top of the log, and `shift-g` to navigate to
+The above commands use `-f` (follow) which will display logs as soon as they are created. You can view older logs by
+removing `-f` from the command, but you will need to use your keyboard to navigate the logs. Use `up`, `down`,
+`page-up` and `page-down` keys. You can also use `g` to navigate to the top of the log, and `shift-g` to navigate to
 the bottom of the logs.
 
 ## API

docs/system/primary-secondary-tertiary.md

@@ -5,6 +5,7 @@ and tertiary options to use your WROLPi may be available.
 
 | Module   | Primary                                   | Secondary                                                                      | Tertiary                                                          |
 |----------|-------------------------------------------|--------------------------------------------------------------------------------|-------------------------------------------------------------------|
+| System   | [React App](../controller/index.md)       | [Controller](../controller/index.md) on port `:8087`                           | CLI tools (systemctl, mount, etc.)                                |
 | Videos   | [React App](../modules/videos/index.md)   | [Open video files with VLC.](../modules/videos/index.md#videos-without-wrolpi) | Open subtitle files with a text editor.                           |
 | Archives | [React App](../modules/archives/index.md) | Open Archive files directly with Chromium                                      | Readability files can be opened with a text editor.               |
 | Map      | [React App](../modules/map/index.md)      | Map is accessible on port `:8084`                                              | None                                                              |

docs/system/systemd.md

@@ -1,8 +1,16 @@
 # Service Control
 
-WROLPi services are controlled by `systemd`.
+WROLPi services can be managed through the [Controller](../controller/services.md) web interface,
+or via command line using `systemd`.
 
-You can view and control the WROLPi services using these commands:
+## Using the Controller (Recommended)
+
+The Controller provides a web-based interface to start, stop, restart services and view logs.
+See [Service Management](../controller/services.md) for details.
+
+## Command Line
+
+For advanced users or scripting, services can be controlled directly with these commands:
 
 | Service   | Status                                        | Logs                                           | Restart                                        | Stop                                        | Start                                        |
 |-----------|-----------------------------------------------|------------------------------------------------|------------------------------------------------|---------------------------------------------|----------------------------------------------|