# 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
```

Edit `.env` with your configuration:

```env
# 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
```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
```


## 🔧 Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `DATABASE_URL` | PostgreSQL connection string | Required |
| `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 18+
- PostgreSQL or Docker
- Git

### Development Commands

```bash
# 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.