176 lines
5.2 KiB
Markdown
176 lines
5.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
git clone https://github.com/michelroegl-brunner/PVESciptslocal.git
|
|
cd PVESciptslocal
|
|
```
|
|
|
|
### 2. Install Dependencies
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### 3. Environment Configuration
|
|
|
|
Copy the example environment file and configure your settings:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
### 4. Start the Application
|
|
|
|
#### Production Mode
|
|
```bash
|
|
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
|
|
```
|
|
|
|
|
|
## 🚀 Development
|
|
|
|
### Prerequisites for Development
|
|
- Node.js 22+
|
|
- Git
|
|
|
|
### Development Commands
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
```
|
|
|
|
# Start development server
|
|
```bash
|
|
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
|
|
- **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
|
|
|
|
|
|
## 📝 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`
|
|
- 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. |