"use client"; import { useState } from "react"; import { Button } from "./ui/button"; import { HelpCircle, Server, Settings, RefreshCw, Clock, Package, HardDrive, FolderOpen, Search, Download, Lock, GitBranch, Archive, } from "lucide-react"; import { useRegisterModal } from "./modal/ModalStackProvider"; interface HelpModalProps { isOpen: boolean; onClose: () => void; initialSection?: string; } type HelpSection = | "server-settings" | "general-settings" | "auth-settings" | "sync-button" | "auto-sync" | "available-scripts" | "downloaded-scripts" | "installed-scripts" | "lxc-settings" | "update-system" | "repositories" | "backups"; export function HelpModal({ isOpen, onClose, initialSection = "server-settings", }: HelpModalProps) { useRegisterModal(isOpen, { id: "help-modal", allowEscape: true, onClose }); const [activeSection, setActiveSection] = useState( initialSection as HelpSection, ); if (!isOpen) return null; const sections = [ { id: "server-settings" as HelpSection, label: "Server Settings", icon: Server, }, { id: "general-settings" as HelpSection, label: "General Settings", icon: Settings, }, { id: "auth-settings" as HelpSection, label: "Authentication Settings", icon: Lock, }, { id: "sync-button" as HelpSection, label: "Sync Button", icon: RefreshCw }, { id: "auto-sync" as HelpSection, label: "Auto-Sync", icon: Clock }, { id: "repositories" as HelpSection, label: "Repositories", icon: GitBranch, }, { id: "available-scripts" as HelpSection, label: "Available Scripts", icon: Package, }, { id: "downloaded-scripts" as HelpSection, label: "Downloaded Scripts", icon: HardDrive, }, { id: "installed-scripts" as HelpSection, label: "Installed Scripts", icon: FolderOpen, }, { id: "lxc-settings" as HelpSection, label: "LXC Settings", icon: Settings, }, { id: "backups" as HelpSection, label: "LXC Backups", icon: Archive }, { id: "update-system" as HelpSection, label: "Update System", icon: Download, }, ]; const renderContent = () => { switch (activeSection) { case "server-settings": return (

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
SSH Key Features:
  • Generate Key Pair: Create new SSH keys automatically
  • View Public Key: Copy public key for server setup
  • Persistent Storage: Keys are stored securely on disk

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.

); case "general-settings": return (

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
); case "auth-settings": return (

Authentication Settings

Secure your application with username and password authentication and configure session management.

Overview

Authentication settings allow you to secure access to your application with username and password protection. Sessions persist across page refreshes, so users don't need to log in repeatedly.

  • • Set up username and password for app access
  • • Enable/disable authentication as needed
  • • Credentials are stored securely using bcrypt hashing
  • • Sessions use secure httpOnly cookies

Setting Up Authentication

  1. Navigate to General Settings → Authentication tab
  2. Enter a username (minimum 3 characters)
  3. Enter a password (minimum 6 characters)
  4. Confirm your password
  5. Click "Save Credentials" to save your authentication settings
  6. Toggle "Enable Authentication" to activate authentication

Session Duration

Configure how long user sessions should last before requiring re-authentication.

  • Configurable Duration: Set session duration from 1 to 365 days
  • Default Duration: Sessions default to 7 days if not configured
  • Session Persistence: Sessions persist across page refreshes and browser restarts
  • New Logins Only: Duration changes apply to new logins, not existing sessions
How to Configure:
  1. Go to General Settings → Authentication tab
  2. Find the "Session Duration" section
  3. Enter the number of days (1-365)
  4. Click "Save" to apply the setting

Session Information

When authenticated, you can view your current session information in the Authentication tab.

  • Time Until Expiration: See how much time remains before your session expires
  • Expiration Date: View the exact date and time your session will expire
  • Auto-Update: The expiration display updates every minute

Updating Credentials

You can change your username and password at any time from the Authentication tab.

  • • Update username without changing password (leave password fields empty)
  • • Change password by entering a new password and confirmation
  • • Both username and password can be updated together
  • • Changes take effect immediately after saving

Security Features

  • Password Hashing: Passwords are hashed using bcrypt before storage
  • Secure Cookies: Authentication tokens stored in httpOnly cookies
  • HTTPS in Production: Cookies are secure (HTTPS-only) in production mode
  • SameSite Protection: Cookies use strict SameSite policy to prevent CSRF attacks
  • JWT Tokens: Sessions use JSON Web Tokens with expiration

⚠️ Important Notes

  • First-Time Setup: You must complete the initial setup before enabling authentication
  • Session Duration: Changes to session duration only affect new logins
  • Logout: You can log out manually, which immediately invalidates your session
  • Lost Credentials: If you forget your password, you'll need to reset it manually in the .env file
  • Disabling Auth: Disabling authentication clears all credentials and allows unrestricted access
); case "sync-button": return (

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
); case "auto-sync": return (

Auto-Sync

Configure automatic synchronization of scripts with configurable intervals and notifications.

What Is Auto-Sync?

Auto-sync automatically synchronizes script metadata from the ProxmoxVE GitHub repository at specified intervals, and optionally downloads/updates scripts and sends notifications.

  • Automatic JSON Sync: Downloads latest script metadata periodically
  • Auto-Download: Automatically download new scripts when available
  • Auto-Update: Automatically update existing scripts to newer versions
  • Notifications: Send notifications when sync completes

Sync Intervals

  • Predefined: Choose from common intervals (15min, 30min, 1hour, 6hours, 12hours, 24hours)
  • Custom Cron: Use cron expressions for advanced scheduling
  • Examples:
    • 0 */6 * * * - Every 6 hours
    • 0 0 * * * - Daily at midnight
    • 0 9 * * 1 - Every Monday at 9 AM

Auto-Download Options

  • Auto-download new scripts: Automatically download scripts that haven't been downloaded yet
  • Auto-update existing scripts:{" "} Automatically update scripts that have newer versions available
  • Selective Control: Enable/disable each option independently

Notifications (Apprise)

Send notifications when sync completes using Apprise, which supports 80+ notification services. If you want any other notification service, please open an issue on the GitHub repository.

  • Apprise Server:{" "} http://YOUR_APPRISE_SERVER/notify/apprise

See the{" "} Apprise documentation {" "} for more supported services.

Setup Guide

  1. Enable auto-sync in the General Settings → Auto-Sync tab
  2. Choose your sync interval (predefined or custom cron)
  3. Configure auto-download options if desired
  4. Set up notifications by adding Apprise URLs
  5. Test your notification setup using the "Test Notification" button
  6. Save your settings to activate auto-sync

Cron Expression Help

Cron expressions have 5 fields: minute hour day month weekday

  • Minute: 0-59 or *
  • Hour: 0-23 or *
  • Day: 1-31 or *
  • Month: 1-12 or *
  • Weekday: 0-6 (Sunday=0) or *

Use{" "} crontab.guru {" "} to test and learn cron expressions.

); case "repositories": return (

Repositories

Manage script repositories (GitHub repositories) and configure which repositories to use for syncing scripts.

What Are Repositories?

Repositories are GitHub repositories that contain scripts and their metadata. Scripts are organized by repositories, allowing you to add custom repositories or manage which repositories are active.

You can add custom repositories or manage existing ones in General Settings > Repositories.

Repository Structure

For a repository to work with this system, it must follow this structure:

  • JSON files: Must be located in a{" "} frontend/public/json/ {" "} folder at the repository root. Each JSON file contains metadata for a script (name, description, installation methods, etc.).
  • Script files: Must be organized in subdirectories:
    • ct/ - Container scripts (LXC)
    • install/{" "} - Installation scripts
    • tools/ - Tool scripts
    • vm/ - Virtual machine scripts

Default Repositories

The system comes with two default repositories that cannot be deleted:

  • Main Repository (ProxmoxVE): The primary repository at{" "} github.com/community-scripts/ProxmoxVE . This is enabled by default and contains stable, production-ready scripts. This repository cannot be deleted.
  • Dev Repository (ProxmoxVED): The development/testing repository at{" "} github.com/community-scripts/ProxmoxVED . This is disabled by default and contains experimental or in-development scripts. This repository cannot be deleted.

Enable vs Disable

You can enable or disable repositories to control which scripts are available:

  • Enabled: Scripts from this repository are included in the Available Scripts tab and will be synced when you sync repositories. Enabled repositories are checked for updates during sync operations.
  • Disabled: Scripts from this repository are excluded from the Available Scripts tab and will not be synced. Scripts already downloaded from a disabled repository remain on your system but won't appear in the list. Disabled repositories are not checked for updates.

Note: Disabling a repository doesn't delete scripts you've already downloaded from it. They remain on your system but are hidden from the Available Scripts list.

Repository Filter Buttons

When multiple repositories are enabled, filter buttons appear in the filter bar on the Available Scripts tab.

  • Each enabled repository gets its own filter button
  • Click a repository button to toggle showing/hiding scripts from that repository
  • Active buttons are highlighted with primary styling
  • Inactive buttons have muted styling
  • This allows you to quickly focus on scripts from specific repositories

Note: Filter buttons only appear when more than one repository is enabled. If only one repository is enabled, all scripts from that repository are shown by default.

Adding Custom Repositories

You can add your own GitHub repositories to access custom scripts:

  1. Go to General Settings > Repositories
  2. Enter the GitHub repository URL (format:{" "} https://github.com/owner/repo )
  3. Choose whether to enable it immediately
  4. Click "Add Repository"

Important: Custom repositories must follow the repository structure described above. Repositories that don't follow this structure may not work correctly.

); case "available-scripts": return (

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
  • Repositories: Filter scripts by repository source (only shown when multiple repositories are enabled). Click repository buttons to toggle visibility of scripts from that repository.

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
); case "downloaded-scripts": return (

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
); case "installed-scripts": return (

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. 1. Connects to your configured PVE servers
  2. 2. Scans LXC container configurations
  3. 3. Looks for containers with community-script tags
  4. 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

💡 How it works:

  • • Scripts automatically detect URLs like{" "} http://10.10.10.1:3000 during installation
  • • Re-detect button runs hostname -I inside the container via SSH
  • • Port defaults to 80, but uses script metadata when available
  • • Web UI buttons are disabled when container is stopped

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
  • Color Coding: Start (green), Stop (red), Update (cyan), Shell (gray), Open UI (blue)
  • 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 <ID>
  • Container Status: Real-time status indicator (running/stopped/unknown)
  • Destroy Button: Permanently remove LXC container with pct destroy <ID>
  • 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
); case "update-system": return (

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:

# 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. 1. Check for Updates: System automatically checks GitHub for new releases
  2. 2. Download Update: Downloads the latest release files
  3. 3. Backup Current Version: Creates backup of current installation
  4. 4. Install New Version: Replaces files and updates dependencies
  5. 5. Build Application: Compiles the updated code
  6. 6. Restart Server: Stops old server and starts new version
  7. 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
); case "lxc-settings": return (

LXC Settings

Edit LXC container configuration files directly from the installed scripts interface. This feature allows you to modify container settings without manually accessing the Proxmox VE server.

Overview

The LXC Settings modal provides a user-friendly interface to edit container configuration files. It parses common settings into editable fields while preserving advanced configurations.

  • Common Settings: Edit basic container parameters like cores, memory, network, and storage
  • Advanced Settings: Raw text editing for lxc.* entries and other advanced configurations
  • Database Caching: Configurations are cached locally for faster access
  • Change Detection: Warns when cached config differs from server version

Common Settings Tab

Basic Configuration
  • Architecture: Container architecture (usually amd64)
  • Cores: Number of CPU cores allocated to the container
  • Memory: RAM allocation in megabytes
  • Swap: Swap space allocation in megabytes
  • Hostname: Container hostname
  • OS Type: Operating system type (e.g., debian, ubuntu)
  • Start on Boot: Whether to start container automatically on host boot
  • Unprivileged: Whether the container runs in unprivileged mode
Network Configuration
  • IP Configuration: Choose between DHCP or static IP assignment
  • IP Address: Static IP with CIDR notation (e.g., 10.10.10.164/24)
  • Gateway: Network gateway for static IP configuration
  • Bridge: Network bridge interface (usually vmbr0)
  • MAC Address: Hardware address for the network interface
  • VLAN Tag: Optional VLAN tag for network segmentation
Storage & Features
  • Root Filesystem: Storage location and disk identifier
  • Size: Disk size allocation (e.g., 4G, 8G)
  • Features: Container capabilities (keyctl, nesting, fuse)
  • Tags: Comma-separated tags for organization

Advanced Settings Tab

The Advanced Settings tab provides raw text editing for configurations not covered in the Common Settings tab.

  • lxc.* entries: Low-level LXC configuration options
  • Comments: Configuration file comments and documentation
  • Custom settings: Any other configuration parameters
  • Preservation: All content is preserved when switching between tabs

Saving Changes

To save configuration changes, you must type the container ID exactly as shown to confirm your changes.

⚠️ Important Warnings
  • • Modifying LXC configuration can break your container
  • • Some changes may require container restart to take effect
  • • Always backup your configuration before making changes
  • • Test changes in a non-production environment first

Sync from Server

The "Sync from Server" button allows you to refresh the configuration from the actual server file, useful when:

  • • Configuration was modified outside of this interface
  • • You want to discard local changes and get the latest server version
  • • The warning banner indicates the cached config differs from server
  • • You want to ensure you're working with the most current configuration

Database Caching

LXC configurations are cached in the database for improved performance and offline access.

  • Automatic caching: Configs are cached during auto-detection and after saves
  • Cache expiration: Cached configs expire after 5 minutes for freshness
  • Change detection: Hash comparison detects external modifications
  • Manual sync: Always available via the "Sync from Server" button
); case "backups": return (

LXC Backups

Create backups of your LXC containers before updates or on-demand. Backups are created using Proxmox VE's built-in backup system and can be stored on any backup-capable storage.

Overview

The backup feature allows you to create snapshots of your LXC containers before performing updates or at any time. Backups are created using the{" "} vzdump command via SSH and stored on your configured Proxmox storage.

  • Pre-Update Backups: Automatically create backups before updating containers
  • Standalone Backups: Create backups on-demand from the Actions menu
  • Storage Selection: Choose from available backup-capable storages
  • Real-Time Progress: View backup progress in the terminal output

Backup Before Update

When updating an LXC container, you can choose to create a backup first:

  1. Click the "Update" button for an installed script
  2. Confirm that you want to update the container
  3. Choose whether to create a backup before updating
  4. If yes, select a backup-capable storage from the list
  5. The backup will be created, then the update will proceed automatically
Backup Failure Handling

If a backup fails, you'll be warned but can still choose to proceed with the update. This ensures updates aren't blocked by backup issues.

Standalone Backup

Create a backup at any time without updating:

  1. Open the Actions dropdown menu for an installed script
  2. Click "Backup"
  3. Select a backup-capable storage from the list
  4. Watch the backup progress in the terminal output

Note: Standalone backups are only available for SSH-enabled scripts with valid container IDs.

Storage Selection

The system automatically discovers backup-capable storages from your Proxmox servers:

  • Automatic Discovery: Storages are fetched from{" "} /etc/pve/storage.cfg {" "} on each server
  • Backup-Capable Only: Only storages with "backup" in their content are shown
  • Cached Results: Storage lists are cached for 1 hour to improve performance
  • Manual Refresh: Use the "Fetch Storages" button to refresh the list if needed
Storage Types
  • Local: Backups stored on the Proxmox host
  • Storage: Network-attached storage (NFS, CIFS, etc.)
  • PBS: Proxmox Backup Server storage

Viewing Available Storages

You can view all storages for a server, including which ones support backups:

  1. Go to the Server Settings section
  2. Find the server you want to check
  3. Click the "View Storages" button (database icon)
  4. See all storages with backup-capable ones highlighted

This helps you identify which storages are available for backups before starting a backup operation.

Backup Process

When a backup is initiated, the following happens:

  • SSH Connection: Connects to the Proxmox server via SSH
  • Command Execution: Runs{" "} vzdump <CTID> --storage <STORAGE> --mode snapshot
  • Real-Time Output: Backup progress is streamed to the terminal
  • Completion: Backup completes and shows success/failure status
  • Sequential Execution: If part of update flow, update proceeds after backup completes

⚠️ Important Notes

  • Storage Requirements: Ensure you have sufficient storage space for backups
  • Backup Duration: Backup time depends on container size and storage speed
  • Snapshot Mode: Backups use snapshot mode, which requires sufficient disk space
  • SSH Access: Backups require valid SSH credentials configured for the server
  • Container State: Containers can be running or stopped during backup

Backup Storage Cache

Storage information is cached to improve performance:

  • Cache Duration: Storage lists are cached for 1 hour
  • Automatic Refresh: Cache expires and refreshes automatically
  • Manual Refresh: Use "Fetch Storages" button to force refresh
  • Per-Server Cache: Each server has its own cached storage list
); default: return null; } }; return (
{/* Header */}

Help & Documentation

{/* Sidebar Navigation */}
{/* Content Area */}
{renderContent()}
); }