From 695232c71192f46d73df3235cf023dfd068418f4 Mon Sep 17 00:00:00 2001 From: Michel Roegl-Brunner Date: Tue, 14 Oct 2025 16:26:34 +0200 Subject: [PATCH] Amend readme --- README.md | 243 +++++++++++++++++++++++++++++++++++++++++++++++ src/app/page.tsx | 2 +- 2 files changed, 244 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 704fb24..a5df90f 100644 --- a/README.md +++ b/README.md @@ -210,6 +210,249 @@ The application uses SQLite for storing server configurations: - **Backup**: Copy `data/settings.db` to backup your server configurations - **Reset**: Delete `data/settings.db` to reset all server configurations +## 📖 Feature Guide + +This section provides detailed information about the application's key features and how to use them effectively. + +### Server Settings + +Manage your Proxmox VE servers and configure connection settings. + +**Adding PVE Servers:** +- **Server Name**: A friendly name to identify your server +- **IP Address**: The IP address or hostname of your PVE server +- **Username**: PVE user account (usually root or a dedicated user) +- **SSH Port**: Default is 22, change if your server uses a different port + +**Authentication Types:** +- **Password**: Use username and password authentication +- **SSH Key**: Use SSH key pair for secure authentication +- **Both**: Try SSH key first, fallback to password if needed + +**Server Color Coding:** +Assign colors to servers for visual distinction throughout the application. This helps identify which server you're working with when managing scripts. This needs to be enabled in the General Settings. + +### General Settings + +Configure application preferences and behavior. + +**Save Filters:** +When enabled, your script filter preferences (search terms, categories, sorting) will be automatically saved and restored when you return to the application: +- Search queries are preserved +- Selected script types are remembered +- Sort preferences are maintained +- Category selections are saved + +**Server Color Coding:** +Enable visual color coding for servers throughout the application. This makes it easier to identify which server you're working with. + +**GitHub Integration:** +Add a GitHub Personal Access Token to increase API rate limits and improve performance: +- Bypasses GitHub's rate limiting for unauthenticated requests +- Improves script loading and syncing performance +- Token is stored securely and only used for API calls + +**Authentication:** +Secure your application with username and password authentication: +- Set up username and password for app access +- Enable/disable authentication as needed +- Credentials are stored securely + +### Sync Button + +Synchronize script metadata from the ProxmoxVE GitHub repository. + +**What Does Syncing Do?** +- **Updates Script Metadata**: Downloads the latest script information (JSON files) +- **Refreshes Available Scripts**: Updates the list of scripts you can download +- **Updates Categories**: Refreshes script categories and organization +- **Checks for Updates**: Identifies which downloaded scripts have newer versions + +**Important Notes:** +- **Metadata Only**: Syncing only updates script information, not the actual script files +- **No Downloads**: Script files are downloaded separately when you choose to install them +- **Last Sync Time**: Shows when the last successful sync occurred +- **Rate Limits**: GitHub API limits may apply without a personal access token + +**When to Sync:** +- When you want to see the latest available scripts +- To check for updates to your downloaded scripts +- If you notice scripts are missing or outdated +- After the ProxmoxVE repository has been updated + +### Available Scripts + +Browse and discover scripts from the ProxmoxVE repository. + +**Browsing Scripts:** +- **Category Sidebar**: Filter scripts by category (Storage, Network, Security, etc.) +- **Search**: Find scripts by name or description +- **View Modes**: Switch between card and list view +- **Sorting**: Sort by name or creation date + +**Filtering Options:** +- **Script Types**: Filter by CT (Container) or other script types +- **Update Status**: Show only scripts with available updates +- **Search Query**: Search within script names and descriptions +- **Categories**: Filter by specific script categories + +**Script Actions:** +- **View Details**: Click on a script to see full information and documentation +- **Download**: Download script files to your local system +- **Install**: Run scripts directly on your PVE servers +- **Preview**: View script content before downloading + +### Downloaded Scripts + +Manage scripts that have been downloaded to your local system. + +**What Are Downloaded Scripts?** +These are scripts that you've downloaded from the repository and are stored locally on your system: +- Script files are stored in your local scripts directory +- You can run these scripts on your PVE servers +- Scripts can be updated when newer versions are available + +**Update Detection:** +The system automatically checks if newer versions of your downloaded scripts are available: +- Scripts with updates available are marked with an update indicator +- You can filter to show only scripts with available updates +- Update detection happens when you sync with the repository + +**Managing Downloaded Scripts:** +- **Update Scripts**: Download the latest version of a script +- **View Details**: See script information and documentation +- **Install/Run**: Execute scripts on your PVE servers +- **Filter & Search**: Use the same filtering options as Available Scripts + +### Installed Scripts + +Track and manage scripts that are installed on your PVE servers. + +**Auto-Detection (Primary Feature):** +The system can automatically detect LXC containers that have community-script tags on your PVE servers: +- **Automatic Discovery**: Scans your PVE servers for containers with community-script tags +- **Container Detection**: Identifies LXC containers running Proxmox helper scripts +- **Server Association**: Links detected scripts to the specific PVE server +- **Bulk Import**: Automatically creates records for all detected scripts + +**How Auto-Detection Works:** +1. Connects to your configured PVE servers +2. Scans LXC container configurations +3. Looks for containers with community-script tags +4. Creates installed script records automatically + +**Manual Script Management:** +- **Add Scripts Manually**: Create records for scripts not auto-detected +- **Edit Script Details**: Update script names and container IDs +- **Delete Scripts**: Remove scripts from tracking +- **Bulk Operations**: Clean up old or invalid script records + +**Script Tracking Features:** +- **Installation Status**: Track success, failure, or in-progress installations +- **Server Association**: Know which server each script is installed on +- **Container ID**: Link scripts to specific LXC containers +- **Web UI Access**: Track and access Web UI IP addresses and ports +- **Execution Logs**: View output and logs from script installations +- **Filtering**: Filter by server, status, or search terms + +**Managing Installed Scripts:** +- **View All Scripts**: See all tracked scripts across all servers +- **Filter by Server**: Show scripts for a specific PVE server +- **Filter by Status**: Show successful, failed, or in-progress installations +- **Sort Options**: Sort by name, container ID, server, status, or date +- **Update Scripts**: Re-run or update existing script installations + +**Web UI Access:** +Automatically detect and access Web UI interfaces for your installed scripts: +- **Auto-Detection**: Automatically detects Web UI URLs from script installation output +- **IP & Port Tracking**: Stores and displays Web UI IP addresses and ports +- **One-Click Access**: Click IP:port to open Web UI in new tab +- **Manual Detection**: Re-detect IP using `hostname -I` inside container +- **Port Detection**: Uses script metadata to get correct port (e.g., actualbudget:5006) +- **Editable Fields**: Manually edit IP and port values as needed + +**Actions Dropdown:** +Clean interface with all actions organized in a dropdown menu: +- **Edit Button**: Always visible for quick script editing +- **Actions Dropdown**: Contains Update, Shell, Open UI, Start/Stop, Destroy, Delete +- **Smart Visibility**: Dropdown only appears when actions are available +- **Auto-Close**: Dropdown closes after clicking any action +- **Disabled States**: Actions are disabled when container is stopped + +**Container Control:** +Directly control LXC containers from the installed scripts page via SSH: +- **Start/Stop Button**: Control container state with `pct start/stop ` +- **Container Status**: Real-time status indicator (running/stopped/unknown) +- **Destroy Button**: Permanently remove LXC container with `pct destroy ` +- **Confirmation Modals**: Simple OK/Cancel for start/stop, type container ID to confirm destroy +- **SSH Execution**: All commands executed remotely via configured SSH connections + +**Safety Features:** +- Start/Stop actions require simple confirmation +- Destroy action requires typing the container ID to confirm +- All actions show loading states and error handling +- Only works with SSH scripts that have valid container IDs + +### Update System + +Keep your PVE Scripts Management application up to date with the latest features and improvements. + +**What Does Updating Do?** +- **Downloads Latest Version**: Fetches the newest release from the GitHub repository +- **Updates Application Files**: Replaces current files with the latest version +- **Installs Dependencies**: Updates Node.js packages and dependencies +- **Rebuilds Application**: Compiles the application with latest changes +- **Restarts Server**: Automatically restarts the application server + +**How to Update:** + +**Automatic Update (Recommended):** +- Click the "Update Now" button when an update is available +- The system will handle everything automatically +- You'll see a progress overlay with update logs +- The page will reload automatically when complete + +**Manual Update (Advanced):** +If automatic update fails, you can update manually: +```bash +# Navigate to the application directory +cd $PVESCRIPTLOCAL_DIR + +# Pull latest changes +git pull + +# Install dependencies +npm install + +# Build the application +npm run build + +# Start the application +npm start +``` + +**Update Process:** +1. **Check for Updates**: System automatically checks GitHub for new releases +2. **Download Update**: Downloads the latest release files +3. **Backup Current Version**: Creates backup of current installation +4. **Install New Version**: Replaces files and updates dependencies +5. **Build Application**: Compiles the updated code +6. **Restart Server**: Stops old server and starts new version +7. **Reload Page**: Automatically refreshes the browser + +**Release Notes:** +Click the external link icon next to the update button to view detailed release notes on GitHub: +- See what's new in each version +- Read about bug fixes and improvements +- Check for any breaking changes +- View installation requirements + +**Important Notes:** +- **Backup**: Your data and settings are preserved during updates +- **Downtime**: Brief downtime occurs during the update process +- **Compatibility**: Updates maintain backward compatibility with your data +- **Rollback**: If issues occur, you can manually revert to previous version + ## 📁 Project Structure ``` diff --git a/src/app/page.tsx b/src/app/page.tsx index b90f3b7..c354bdc 100644 --- a/src/app/page.tsx +++ b/src/app/page.tsx @@ -147,7 +147,7 @@ export default function Home() { {/* Header */}

- + PVE Scripts Management