From 547a72256dda92a4b544da3973c512669b66b2fc Mon Sep 17 00:00:00 2001 From: "courtmanr@gmail.com" Date: Sun, 20 Apr 2025 18:05:31 +0100 Subject: [PATCH] docs: Update README for simplified app and add .env.example --- .gitignore | 21 ++++++ README.md | 152 ++++++++++++++++++++++++++++++++++++++++++++ server/.env.example | 16 +++++ 3 files changed, 189 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 server/.env.example diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..3082a3b74 --- /dev/null +++ b/.gitignore @@ -0,0 +1,21 @@ +# Node dependencies +node_modules/ +server/node_modules/ + +# Environment variables +.env +server/.env + +# Logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +lerna-debug.log* + +# Build outputs +build/ +dist/ + +# Optional files +.DS_Store \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 000000000..d522cee54 --- /dev/null +++ b/README.md @@ -0,0 +1,152 @@ +# Pulse Logo Pulse for Proxmox VE (Simplified) + +A lightweight monitoring application for Proxmox VE that displays real-time status for VMs and containers via a simple web interface. + +[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/rcourtman) + +## 📋 Table of Contents +- [Configuration](#️-configuration) + - [Environment Variables](#environment-variables) + - [Creating a Proxmox API Token](#creating-a-proxmox-api-token) + - [Required Permissions](#required-permissions) +- [Installation](#-installation) +- [Running the Application](#-running-the-application) +- [Features](#-features) +- [System Requirements](#-system-requirements) +- [Contributing](#-contributing) +- [License](#-license) +- [Trademark Notice](#trademark-notice) +- [Support](#-support) + +## 🛠️ Configuration + +### Environment Variables + +1. **Copy Example File:** This application requires environment variables for configuration. Copy the example environment file from `server/.env.example` to `server/.env`. + + ```bash + cp server/.env.example server/.env + ``` + +2. **Edit `.env`:** Open `server/.env` in a text editor and update the values for your Proxmox environment, including the Host, Token ID, and Token Secret obtained below. + + The following variables are available: + - `PROXMOX_HOST`: URL of your Proxmox server (e.g., `https://your-proxmox-ip:8006`). + - `PROXMOX_TOKEN_ID`: Your API Token ID (e.g., `user@pam!tokenid`). + - `PROXMOX_TOKEN_SECRET`: Your API Token Secret. + - `PROXMOX_ALLOW_SELF_SIGNED_CERTS`: (Optional) Set to `true` if your Proxmox server uses self-signed SSL certificates. Defaults to `false`. + - `PORT`: (Optional) Port for the Pulse server to listen on. Defaults to `7655`. + - `PROXMOX_USERNAME`, `PROXMOX_PASSWORD`, `PROXMOX_REALM`: (Optional) Fallback credentials if API token is not provided. + +### Creating a Proxmox API Token + +An API token is recommended for connecting Pulse to Proxmox. + +1. **Log in to the Proxmox web interface** + +2. **Create a dedicated user** (optional but recommended for security) + * Go to `Datacenter` → `Permissions` → `Users`. + * Click `Add`. + * Enter a `User name` (e.g., "pulse-monitor"), set Realm to `Proxmox VE authentication server`, set a password, and ensure `Enabled` is checked. Click `Add`. + +3. **Create an API token** + * Go to `Datacenter` → `Permissions` → `API Tokens`. + * Click `Add`. + * Select the `User` you created (e.g., "pulse-monitor@pam") or `root@pam`. + * Enter a `Token ID` (e.g., "pulse"). + * Leave `Privilege Separation` checked (more secure). + * Click `Add`. + * **Important:** Copy the displayed `Secret` value immediately and store it securely. It will only be shown once. + +4. **Assign permissions** + * Go to `Datacenter` → `Permissions` → `Add` → `User Permission`. + * Path: `/` + * User: Select the user the token belongs to (e.g., "pulse-monitor@pam"). + * Role: `PVEAuditor` (provides read-only access). + * Ensure `Propagate` is checked. + * Click `Add`. + +5. **Update your `server/.env` file** with the `Token ID` (which looks like `user@realm!tokenid`, e.g., `pulse-monitor@pam!pulse`) and the `Secret` you saved. + +### Required Permissions + +The `PVEAuditor` role is recommended as it provides the necessary read-only permissions for Pulse to monitor your Proxmox environment: +- `Datastore.Audit` +- `Permissions.Read` (implicitly included) +- `Pool.Audit` +- `Sys.Audit` +- `VM.Audit` + +## 💾 Installation + +Navigate to the project root directory and install the necessary Node.js dependencies. + +```bash +# Install root dependencies +npm install +``` + +You also need to install dependencies for the server component: + +```bash +# Install server dependencies +cd server +npm install +cd .. +``` + +## ▶️ Running the Application + +### Development Mode + +To run the application in development mode (useful for testing changes): + +```bash +npm run dev +``` +This command starts the server, typically using `nodemon` or similar for automatic restarts on file changes. Check the terminal output for the URL (e.g., `http://localhost:7655`). + +### Production Mode + +To run the application normally: + +```bash +npm run start +``` +This command starts the server using `node`. Access the application via the configured host and port. + +## ✨ Features + +- Lightweight monitoring for Proxmox VE nodes. +- Displays real-time status for VMs and Containers. +- Simple web interface. + +## 💻 System Requirements + +- **Node.js**: Version 16.x or higher recommended (check `package.json` engines for specifics). +- **Network**: Connectivity between the Pulse server and your Proxmox server(s). +- **Proxmox**: A running Proxmox VE instance with API access enabled. + +## 👥 Contributing + +Contributions are welcome! Please follow standard fork-and-pull-request workflow. Refer to the main repository's contributing guidelines if available. + +1. **Fork the repository** +2. **Create a feature branch**: `git checkout -b feature/your-feature` +3. **Commit your changes**: `git commit -m 'Add your feature'` +4. **Push to the branch**: `git push origin feature/your-feature` +5. **Open a Pull Request** + +## 📄 License + +Specify the license under which this project is distributed (e.g., MIT License). *(Consider adding the actual license file if missing)* + +## Trademark Notice + +Proxmox® and Proxmox VE® are registered trademarks of Proxmox Server Solutions GmbH. Pulse for Proxmox VE is an independent project and is not affiliated with, endorsed by, or sponsored by Proxmox Server Solutions GmbH. + +## ❤️ Support + +If you find Pulse helpful, please consider supporting its development through Ko-fi. Your support helps keep this project maintained and free for everyone! + +[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/rcourtman) \ No newline at end of file diff --git a/server/.env.example b/server/.env.example new file mode 100644 index 000000000..cabc34470 --- /dev/null +++ b/server/.env.example @@ -0,0 +1,16 @@ +# Proxmox Connection Details +PROXMOX_HOST=https://your-proxmox-ip-or-hostname:8006 +PROXMOX_TOKEN_ID=your-api-token-id@pam!your-token-name +PROXMOX_TOKEN_SECRET=your-api-token-secret-uuid + +# Optional: Allow connections to servers with self-signed certificates (true/false) +# Set to true if you haven't configured valid SSL certificates for Proxmox +PROXMOX_ALLOW_SELF_SIGNED_CERTS=true + +# Optional: Define the port the Pulse server listens on (defaults internally to 7655) +# PORT=7655 + +# Optional: Fallback credentials if API token is not provided +# PROXMOX_USERNAME=root +# PROXMOX_PASSWORD=your-password +# PROXMOX_REALM=pam \ No newline at end of file