6.6 KiB
6.6 KiB
PVE Scripts Local 🚀
A modern web-based management interface for Proxmox VE (PVE) helper scripts. This tool provides a user-friendly way to discover, download, and execute community-sourced Proxmox scripts locally with real-time terminal output streaming.
🌟 Features
- Web-based Interface: Modern React/Next.js frontend with real-time terminal emulation
- Script Discovery: Browse and search through community Proxmox scripts from GitHub
- One-Click Execution: Run scripts directly from the web interface with live output
- Real-time Terminal: Full terminal emulation with xterm.js for interactive script execution
- Script Management: Download, update, and manage local script collections
- Security: Sandboxed script execution with path validation and time limits
- Database Integration: PostgreSQL backend for script metadata and execution history
- WebSocket Communication: Real-time bidirectional communication for script execution
🏗️ Architecture
Frontend
- Next.js 15 with React 19
- TypeScript for type safety
- Tailwind CSS for styling
- xterm.js for terminal emulation
- tRPC for type-safe API communication
Backend
- Node.js server with WebSocket support
- PostgreSQL database with Prisma ORM
- WebSocket Server for real-time script execution
- Script Downloader Service for GitHub integration
Scripts
- Core Functions: Shared utilities and build functions
- Container Scripts: Pre-configured LXC container setups
- Installation Scripts: System setup and configuration tools
📋 Prerequisites
- Node.js 18+ and npm
- PostgreSQL database (or Docker/Podman for local development)
- Git for cloning the repository
- Linux/Unix environment (tested on Proxmox VE hosts)
🚀 Installation
1. Clone the Repository
git clone https://github.com/michelroegl-brunner/PVESciptslocal.git
cd PVESciptslocal
2. Install Dependencies
npm install
3. Environment Configuration
Copy the example environment file and configure your settings:
cp .env.example .env
Edit .env with your configuration:
# Database Configuration
DATABASE_URL="postgresql://postgres:password@localhost:5432/pve-scripts-local"
# GitHub Repository Configuration
REPO_URL="https://github.com/community-scripts/ProxmoxVE"
REPO_BRANCH="main"
SCRIPTS_DIRECTORY="scripts/ct"
# Security Settings
MAX_SCRIPT_EXECUTION_TIME="300000"
ALLOWED_SCRIPT_PATHS="scripts/"
# WebSocket Configuration
WEBSOCKET_PORT="3000"
4. Start the Application
Production Mode
npm run build
npm start
The application will be available at http://IP:3000
🎯 Usage
1. Access the Web Interface
Open your browser and navigate to http://IP:3000 (or your configured host/port).
2. Browse Available Scripts
- The main page displays a grid of available Proxmox scripts
- Use the search functionality to find specific scripts
- Scripts are categorized by type (containers, installations, etc.)
3. Download Scripts
- Click on any script card to view details
- Use the "Download" button to fetch scripts from GitHub
- Downloaded scripts are stored locally in the
scripts/directory
4. Execute Scripts
- Click "Run Script" on any downloaded script
- A terminal window will open with real-time output
- Interact with the script through the web terminal
- Use the close button to stop execution
5. Script Management
- View script execution history
- Update scripts to latest versions
- Manage local script collections
📁 Project Structure
PVESciptslocal/
├── scripts/ # Script collection
│ ├── core/ # Core utility functions
│ │ ├── build.func # Build system functions
│ │ ├── tools.func # Tool installation functions
│ │ └── create_lxc.sh # LXC container creation
│ ├── ct/ # Container templates
│ └── install/ # Installation scripts
├── src/ # Source code
│ ├── app/ # Next.js app directory
│ │ ├── _components/ # React components
│ │ └── page.tsx # Main page
│ └── server/ # Server-side code
│ └── services/ # Business logic services
├── prisma/ # Database schema
├── public/ # Static assets
├── server.js # Main server file
└── package.json # Dependencies and scripts
🔧 Configuration
Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|np,
| REPO_URL | GitHub repository URL | Required |
| REPO_BRANCH | Git branch to use | main |
| SCRIPTS_DIRECTORY | Local scripts directory | scripts/ct |
| MAX_SCRIPT_EXECUTION_TIME | Max execution time (ms) | 300000 |
| ALLOWED_SCRIPT_PATHS | Allowed script paths | scripts/ |
Database Configuration
The application uses PostgreSQL with Prisma ORM. The database stores:
- Script metadata and descriptions
- Execution history and logs
- User preferences and settings
🚀 Development
Prerequisites for Development
- Node.js 22+
- Git
Development Commands
# Install dependencies
npm install
# Start development server
npm run dev:server
### Project Structure for Developers
- **Frontend**: React components in `src/app/_components/`
- **Backend**: Server logic in `src/server/`
- **API**: tRPC routers for type-safe API communication
- **Database**: Prisma schema in `prisma/schema.prisma`
- **Scripts**: Bash scripts in `scripts/` directory
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
### Adding New Scripts
1. Create a new `.sh` file in the appropriate directory (`scripts/ct/` for containers)
2. Follow the existing script structure and include proper headers
3. Test the script thoroughly
4. Submit a pull request with the new script
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
### Logs
- Server logs: Check console output or `server.log`
- Database logs: Check PostgreSQL logs
- Script execution: View in web terminal
---
**Note**: This is alpha software. Use with caution in production environments and always backup your Proxmox configuration before running scripts.