diff --git a/.dockerignore b/.dockerignore deleted file mode 100644 index 48232282e..000000000 --- a/.dockerignore +++ /dev/null @@ -1,37 +0,0 @@ -# Node modules -node_modules -frontend/node_modules - -# Build artifacts -dist -frontend/dist - -# Logs -logs -*.log -npm-debug.log* - -# Environment variables -.env -.env.local -.env.development.local -.env.test.local -.env.production.local - -# Git -.git -.gitignore - -# IDE files -.idea -.vscode -*.swp -*.swo - -# Reports and test files -reports -coverage - -# Temporary files -.DS_Store -Thumbs.db \ No newline at end of file diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml deleted file mode 100644 index 0babf392a..000000000 --- a/.github/FUNDING.yml +++ /dev/null @@ -1,13 +0,0 @@ -# These are supported funding model platforms - -github: [rcourtman] -patreon: # Replace with a single Patreon username -open_collective: # Replace with a single Open Collective username -ko_fi: # Replace with a single Ko-fi username -tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel -community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry -liberapay: # Replace with a single Liberapay username -issuehunt: # Replace with a single IssueHunt username -otechie: # Replace with a single Otechie username -lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry -custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2'] \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/docker-issue.md b/.github/ISSUE_TEMPLATE/docker-issue.md deleted file mode 100644 index e81368c93..000000000 --- a/.github/ISSUE_TEMPLATE/docker-issue.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -name: Docker Issue -about: Report an issue with the Docker image -title: '[DOCKER] ' -labels: docker -assignees: '' ---- - -## Docker Issue - -**Docker Image Version:** - - -**Environment:** - - -**Issue Description:** - - -**Steps to Reproduce:** - - -**Expected Behavior:** - - -**Actual Behavior:** - - -**Docker Run Command:** - -```bash -docker run -d -p 7654:7654 --env-file .env --name pulse-app rcourtman/pulse:latest -``` - -**Additional Context:** - \ No newline at end of file diff --git a/.github/workflows/README.md b/.github/workflows/README.md deleted file mode 100644 index 8bfafbc4f..000000000 --- a/.github/workflows/README.md +++ /dev/null @@ -1,29 +0,0 @@ -# Version Update Workflow - -This GitHub workflow automatically updates the application version when a new release is created. - -## How it works - -1. When you create a new release on GitHub, the workflow is triggered -2. It updates the `frontend/src/utils/version.js` file with the new version number -3. It also updates the version in both the root and frontend `package.json` files -4. The changes are committed and pushed back to the repository - -## Creating a new release - -To create a new release and update the version displayed in the app: - -1. Go to your GitHub repository -2. Click on "Releases" in the right sidebar -3. Click "Create a new release" or "Draft a new release" -4. Enter a tag version (e.g., `v1.0.1` or `1.0.1`) -5. Add a title and description for your release -6. Click "Publish release" - -The workflow will automatically update the version in your codebase. - -## Notes - -- The version displayed in the app header will be updated to match the release tag -- If you use a tag with a 'v' prefix (e.g., `v1.0.1`), the 'v' will be removed in the version file, but the app already adds the 'v' when displaying it -- Make sure your repository has the necessary permissions for the GitHub Action to push changes \ No newline at end of file diff --git a/.github/workflows/docker-publish.yml.disabled b/.github/workflows/docker-publish.yml.disabled deleted file mode 100644 index 17c9c6995..000000000 --- a/.github/workflows/docker-publish.yml.disabled +++ /dev/null @@ -1,60 +0,0 @@ -name: Publish Docker image - -on: - release: - types: [published] - -jobs: - push_to_registry: - name: Push Docker image to Docker Hub - runs-on: ubuntu-latest - steps: - - name: Check out the repo - uses: actions/checkout@v3 - with: - ref: main # Ensure we get the latest version updates - - - name: Set up QEMU - uses: docker/setup-qemu-action@v2 - with: - platforms: 'arm64,amd64' - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v2 - - - name: Log in to Docker Hub - uses: docker/login-action@v2 - with: - username: ${{ secrets.DOCKER_USERNAME }} - password: ${{ secrets.DOCKER_PASSWORD }} - - - name: Extract metadata (tags, labels) for Docker - id: meta - uses: docker/metadata-action@v4 - with: - images: rcourtman/pulse - tags: | - type=semver,pattern={{version}} - type=semver,pattern={{major}}.{{minor}} - latest - - - name: Build and push Docker image - uses: docker/build-push-action@v4 - with: - context: . - push: true - platforms: linux/amd64,linux/arm64 - tags: ${{ steps.meta.outputs.tags }} - labels: ${{ steps.meta.outputs.labels }} - target: production - cache-from: type=gha - cache-to: type=gha,mode=max - - - name: Update Docker Hub Description - uses: peter-evans/dockerhub-description@v3 - with: - username: ${{ secrets.DOCKER_USERNAME }} - password: ${{ secrets.DOCKER_PASSWORD }} - repository: rcourtman/pulse - short-description: "Real-time ProxMox monitoring with CPU, memory, network, and disk metrics across nodes." - readme-filepath: ./README.md \ No newline at end of file diff --git a/.github/workflows/update-version.yml.disabled b/.github/workflows/update-version.yml.disabled deleted file mode 100644 index a145122cb..000000000 --- a/.github/workflows/update-version.yml.disabled +++ /dev/null @@ -1,41 +0,0 @@ -name: Update Version - -on: - release: - types: [published] - -jobs: - update-version: - runs-on: ubuntu-latest - permissions: - contents: write - steps: - - uses: actions/checkout@v3 - with: - ref: main - - - name: Setup Node.js - uses: actions/setup-node@v3 - with: - node-version: 18 - - - name: Update version file - run: | - # Extract version from the release tag (remove 'v' prefix if present) - VERSION=$(echo ${{ github.ref_name }} | sed 's/^v//') - - # Create utils directory if it doesn't exist - mkdir -p frontend/src/utils - - # Update the version.js file - echo "// This file contains the version information for the application" > frontend/src/utils/version.js - echo "// It is automatically updated when a new release is created" >> frontend/src/utils/version.js - echo "" >> frontend/src/utils/version.js - echo "export const VERSION = '$VERSION'; // Updated by GitHub Actions" >> frontend/src/utils/version.js - - - name: Commit and push if changed - run: | - git config --global user.name 'GitHub Actions' - git config --global user.email 'actions@github.com' - git add frontend/src/utils/version.js - git diff --staged --quiet || (git commit -m "Update version to ${{ github.ref_name }}" && git push) \ No newline at end of file diff --git a/Dockerfile b/Dockerfile index fcbdc8a80..993822743 100644 --- a/Dockerfile +++ b/Dockerfile @@ -19,7 +19,7 @@ RUN npm run build RUN cd frontend && npm run build # Production stage -FROM node:18-slim AS production +FROM node:18-slim # Create a non-root user RUN apt-get update && apt-get install -y --no-install-recommends dumb-init \ @@ -29,35 +29,10 @@ RUN apt-get update && apt-get install -y --no-install-recommends dumb-init \ WORKDIR /app -# Add labels for better metadata -LABEL org.opencontainers.image.title="ProxMox Pulse" -LABEL org.opencontainers.image.description="A lightweight, responsive ProxMox monitoring application" -LABEL org.opencontainers.image.version="1.0.13" -LABEL org.opencontainers.image.authors="Richard Courtman" -LABEL org.opencontainers.image.url="https://github.com/rcourtman/pulse" -LABEL org.opencontainers.image.source="https://github.com/rcourtman/pulse" -LABEL org.opencontainers.image.licenses="MIT" - -# Define build arguments with defaults -ARG NODE_ENV=production -ARG LOG_LEVEL=info -ARG ENABLE_DEV_TOOLS=false -ARG PORT=7654 -ARG NODE_TLS_REJECT_UNAUTHORIZED=0 - -# Set environment variables from build arguments -ENV NODE_ENV=${NODE_ENV} -ENV LOG_LEVEL=${LOG_LEVEL} -ENV ENABLE_DEV_TOOLS=${ENABLE_DEV_TOOLS} -ENV PORT=${PORT} -ENV DOCKER_CONTAINER=true -ENV NODE_TLS_REJECT_UNAUTHORIZED=${NODE_TLS_REJECT_UNAUTHORIZED} - # Copy only necessary files from builder stage COPY --from=builder /app/package*.json ./ COPY --from=builder /app/dist ./dist COPY --from=builder /app/frontend/dist ./frontend/dist -COPY --from=builder /app/start-dev.sh ./ # Create a symbolic link from /app/dist/public to /app/frontend/dist RUN mkdir -p /app/dist/public && rm -rf /app/dist/public && ln -s /app/frontend/dist /app/dist/public @@ -65,59 +40,18 @@ RUN mkdir -p /app/dist/public && rm -rf /app/dist/public && ln -s /app/frontend/ # Install only production dependencies RUN npm ci --only=production -# Make the startup script executable -RUN chmod +x start-dev.sh && chown -R pulse:pulse /app +# Set production environment +ENV NODE_ENV=production \ + PORT=7654 # Switch to non-root user USER pulse # Expose the backend port -EXPOSE ${PORT} +EXPOSE 7654 -# Use dumb-init as entrypoint to handle signals properly +# Use dumb-init to handle signals properly ENTRYPOINT ["/usr/bin/dumb-init", "--"] # Start the application -CMD ["node", "dist/server.js"] - -# Development stage for local development -FROM node:18 AS development - -WORKDIR /app - -# Copy package files -COPY package*.json ./ -COPY frontend/package*.json ./frontend/ - -# Install dependencies -RUN npm ci -RUN cd frontend && npm ci - -# Copy application files -COPY . . - -# Make the startup script executable -RUN chmod +x start-dev.sh - -# Define build arguments with defaults -ARG NODE_ENV=development -ARG LOG_LEVEL=debug -ARG ENABLE_DEV_TOOLS=true -ARG PORT=7654 -ARG VITE_PORT=9513 -ARG NODE_TLS_REJECT_UNAUTHORIZED=0 - -# Set environment variables from build arguments -ENV NODE_ENV=${NODE_ENV} -ENV LOG_LEVEL=${LOG_LEVEL} -ENV ENABLE_DEV_TOOLS=${ENABLE_DEV_TOOLS} -ENV PORT=${PORT} -ENV VITE_PORT=${VITE_PORT} -ENV DOCKER_CONTAINER=true -ENV NODE_TLS_REJECT_UNAUTHORIZED=${NODE_TLS_REJECT_UNAUTHORIZED} - -# Expose the backend and frontend ports -EXPOSE ${PORT} ${VITE_PORT} - -# Start both the backend and frontend (using the start-dev.sh script) -CMD ["./start-dev.sh"] \ No newline at end of file +CMD ["node", "dist/server.js"] \ No newline at end of file diff --git a/README.md b/README.md index 52a91d40a..f741592af 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,10 @@ # ProxMox Pulse -[![Docker Pulls](https://img.shields.io/docker/pulls/rcourtman/pulse.svg)](https://hub.docker.com/r/rcourtman/pulse) - A lightweight, responsive ProxMox monitoring application that displays real-time metrics for CPU, memory, network, and disk usage across multiple nodes. ## Quick Start -### 🚀 Run with Docker (Production) -```bash -# 1. Create .env file with your ProxMox details -cat > .env << EOL -PROXMOX_NODE_1_NAME=My Proxmox -PROXMOX_NODE_1_HOST=https://proxmox.local:8006 -PROXMOX_NODE_1_TOKEN_ID=root@pam!pulse -PROXMOX_NODE_1_TOKEN_SECRET=your-token-secret -EOL - -# 2. Run the container -docker run -d -p 7654:7654 --env-file .env --name pulse-app rcourtman/pulse:latest - -# 3. Open in browser -open http://localhost:7654 # or visit in your browser -``` - -### 💻 Development Setup +### 💻 Development ```bash # 1. Clone and install git clone https://github.com/rcourtman/pulse.git @@ -41,7 +22,11 @@ cp .env.example .env open http://localhost:3000 # or visit in your browser ``` -For detailed setup instructions, see the [Installation](#installation) section. +### 🚀 Production +```bash +# Just want to run it? Use Docker: +docker run -d -p 7654:7654 --env-file .env --name pulse-app rcourtman/pulse:latest +``` ## Features @@ -49,7 +34,6 @@ For detailed setup instructions, see the [Installation](#installation) section. - Dashboard with summary cards for nodes, guests, and resources - Responsive design that works on desktop and mobile - WebSocket connection for live updates -- Automatic version display linked to GitHub releases ## Screenshots @@ -67,8 +51,9 @@ For detailed setup instructions, see the [Installation](#installation) section. ⚠️ Note: These screenshots are examples only. The actual interface may vary based on your ProxMox setup and version. -## Project Structure +## Development +### Project Structure ``` pulse/ ├── frontend/ # React frontend application @@ -88,663 +73,106 @@ pulse/ │ └── server.ts # Main server entry point │ ├── scripts/ # Development and utility scripts -├── .github/ # GitHub Actions workflows -├── docker/ # Docker configuration files ├── .env.example # Example environment variables └── package.json # Backend dependencies ``` -### Key Components - -#### Frontend -- Built with React and TypeScript -- Uses Vite for development server and building -- Styled with Tailwind CSS -- Real-time updates via WebSocket connection - -#### Backend -- Node.js with Express -- TypeScript for type safety -- WebSocket server for real-time updates -- ProxMox API integration with error handling - -#### Development Tools -- ESLint for code linting -- TypeScript for type checking -- Docker for production deployment -- GitHub Actions for CI/CD - -## Development vs Production Modes - -The application runs differently in development and production modes: - -### Quick Reference - -| Feature | Development Mode | Production Mode | -|---------|-----------------|-----------------| -| Start Command | `./start-dev.sh` or `npm run dev:start` | `docker-compose up -d pulse` | -| Frontend URL | http://localhost:3000 | http://localhost:7654 | -| Backend URL | http://localhost:7654 | http://localhost:7654 | -| Hot Reloading | Yes | No | -| Source Maps | Yes | No | -| Detailed Logging | Yes | No | -| Build Required | No | Yes | -| Best For | Local development, debugging | Deployment, production use | - ### Development Mode -When running with `./start-dev.sh` or `npm run dev:start`: +When running with `./start-dev.sh`: - Frontend (Vite dev server): http://localhost:3000 - Backend (API + WebSocket): http://localhost:7654 -- Frontend automatically proxies API/WebSocket requests to backend - Hot-reloading enabled for both frontend and backend - Source maps and detailed logging available -- Development tools and debugging features enabled - Changes to code are reflected immediately -### Production Mode -When running with Docker or `NODE_ENV=production`: -- Everything runs on a single port: http://localhost:7654 -- Backend serves the built frontend files directly -- No development servers or hot-reloading -- Optimized for performance and security -- Minimal dependencies and logging -- Requires a build step before deployment +### Available Commands +```bash +# Development +npm run dev:start # Start both frontend and backend (same as ./start-dev.sh) +npm run dev:kill:all # Kill all development servers -## Versioning +# Testing +npm run test:startup # Run startup checks +npm run test:api # Test ProxMox API connection +npm run lint # Run ESLint -The application version displayed in the header is automatically updated when a new GitHub release is created. This is handled by a GitHub Actions workflow that: - -1. Updates the version in the source code when a release is published -2. Updates the package.json files to match the release version -3. Commits and pushes these changes back to the repository - -For more details on how to create releases, see the [workflow documentation](.github/workflows/README.md). - -## Environment Variables - -### Backend Environment Variables - -The backend server uses the following environment variables, which can be set in the `.env` file: - -#### Common Settings -- `PORT`: The port on which the server will run (default: 7654) -- `NODE_ENV`: Set to `production` for production or `development` for development -- `METRICS_HISTORY_MINUTES`: How many minutes of metrics history to keep (default: 60) -- `NODE_POLLING_INTERVAL_MS`: How often to poll nodes for updates (default: 10000) -- `EVENT_POLLING_INTERVAL_MS`: How often to poll for events (default: 2000) - -#### Development-only Settings -- `LOG_LEVEL`: Log level (`error`, `warn`, `info`, `debug`) - defaults to `debug` in development -- `ENABLE_DEV_TOOLS`: Enable development tools (`true` or `false`) - defaults to `true` in development -- `IGNORE_SSL_ERRORS`: Whether to ignore SSL errors when connecting to ProxMox nodes - defaults to `true` in development -- `NODE_TLS_REJECT_UNAUTHORIZED`: Set to `0` to disable SSL certificate validation - defaults to `0` in development - -#### Production-only Settings -- `LOG_LEVEL`: Log level (`error`, `warn`, `info`, `debug`) - defaults to `error` in production -- `ENABLE_DEV_TOOLS`: Enable development tools (`true` or `false`) - defaults to `false` in production -- `IGNORE_SSL_ERRORS`: Whether to ignore SSL errors when connecting to ProxMox nodes - defaults to `false` in production -- `NODE_TLS_REJECT_UNAUTHORIZED`: Set to `1` to enable SSL certificate validation - defaults to `1` in production - -### Frontend Environment Variables - -The frontend can be configured using the following environment variables: - -#### Development Mode -- `VITE_API_URL`: The URL of the backend API (defaults to `http://localhost:7654` in development) - -#### Production Mode -- `VITE_API_URL`: The URL of the backend API (defaults to the current origin in production) - -### Security Considerations - -#### Development Mode -For development or internal networks, the default settings are: +# Building +npm run build # Build the TypeScript backend ``` + +## Configuration + +### Environment Variables +Create a `.env` file based on `.env.example`: + +```bash +# Required: ProxMox Node Configuration +PROXMOX_NODE_1_NAME=Proxmox Node 1 +PROXMOX_NODE_1_HOST=https://proxmox.local:8006 +PROXMOX_NODE_1_TOKEN_ID=root@pam!pulse +PROXMOX_NODE_1_TOKEN_SECRET=your-token-secret + +# Optional: Additional nodes +PROXMOX_NODE_2_NAME=Proxmox Node 2 +PROXMOX_NODE_2_HOST=https://proxmox2.local:8006 +PROXMOX_NODE_2_TOKEN_ID=root@pam!pulse +PROXMOX_NODE_2_TOKEN_SECRET=your-token-secret + +# Development Settings (adjust as needed) +PORT=7654 +NODE_ENV=development LOG_LEVEL=debug -ENABLE_DEV_TOOLS=true -IGNORE_SSL_ERRORS=true -NODE_TLS_REJECT_UNAUTHORIZED=0 +METRICS_HISTORY_MINUTES=60 +NODE_POLLING_INTERVAL_MS=2000 +EVENT_POLLING_INTERVAL_MS=1000 ``` -#### Production Mode -For production deployments, the recommended secure settings are: -``` -LOG_LEVEL=error -ENABLE_DEV_TOOLS=false -IGNORE_SSL_ERRORS=false -NODE_TLS_REJECT_UNAUTHORIZED=1 -``` - -⚠️ **Important**: Never use development security settings in production, as they disable important security features. - -## Prerequisites - -### Development Requirements -- Node.js 18 or higher -- npm 8 or higher -- Git -- Access to a ProxMox server -- A ProxMox API token with appropriate permissions - -### Production Requirements -- Docker Engine 20.10.0 or higher -- Docker Compose v2.0.0 or higher (if using docker-compose) -- Access to a ProxMox server -- A ProxMox API token with appropriate permissions -- Valid SSL certificates (recommended) - ### ProxMox API Token Requirements -Your ProxMox API token needs the following permissions: +Your ProxMox API token needs these permissions: - PVEAuditor role or custom role with: - Datastore.Audit - VM.Audit - Sys.Audit - Pool.Audit -## Compatibility - -### Tested Environments - -#### ProxMox VE Versions -- Fully tested on ProxMox VE 7.x and 8.x -- Should work with ProxMox VE 6.x (not actively tested) -- Earlier versions are not supported - -#### Operating Systems -- Linux (Ubuntu 20.04+, Debian 11+) -- macOS (Monterey 12.0+) -- Windows 10/11 with WSL2 - -#### Browsers -- Chrome/Chromium 90+ -- Firefox 90+ -- Safari 15+ -- Edge 90+ - -#### Container Platforms -- Docker 20.10.0+ -- Podman 3.0+ (experimental) -- Kubernetes 1.20+ (with appropriate volume mounts) - -### Known Limitations -- Internet Explorer is not supported -- Mobile browsers have limited functionality -- Some features may not work with ProxMox VE 6.x -- WebSocket connections may be blocked by some corporate firewalls - -## Installation - -### Development Setup - -1. Clone the repository -2. Install dependencies: - ``` - npm install - ``` -3. Install frontend dependencies: - ``` - cd frontend && npm install - ``` -4. Create a `.env` file based on the `.env.example` file -5. Start the development server: - ``` - ./start-dev.sh - ``` -6. Access the application at http://localhost:3000 - -### Development Tools - -The following npm scripts are available for development: - -```bash -# Start the application in development mode -npm run dev:start # Starts both frontend and backend (same as ./start-dev.sh) -npm run dev:frontend # Start only the frontend dev server -npm run dev:server # Start only the backend dev server - -# Development utilities -npm run dev:kill:all # Kill all development servers -npm run dev:kill:frontend # Kill only the frontend dev server -npm run dev:kill:backend # Kill only the backend dev server - -# Testing and validation -npm run test:startup # Run startup checks -npm run test:api # Test ProxMox API connection -npm run lint # Run ESLint - -# Production build -npm run build # Build the TypeScript backend -``` - -#### Release Process - -> **⚠️ Note for Contributors**: The release process is restricted to repository maintainers only. -> -> Regular contributors should not attempt to create releases. Instead, please follow the [Contributing](#contributing) guidelines for submitting changes. -> -> Repository maintainers use internal tools to handle: -> - Version bumping (patch, minor, major) -> - Updating version in all relevant files -> - Git tagging and pushing -> - Docker image building and pushing -> - GitHub release creation - -These commands are particularly useful when: -- You need to restart specific components -- You're debugging connection issues -- You want to validate your ProxMox API configuration -- You're preparing for production deployment - -### Production Setup with Docker - -1. Clone the repository -2. Copy the example environment file and configure it: - ``` - cp .env.example .env - ``` -3. Edit the `.env` file with your ProxMox node details -4. Start the application: - ``` - docker-compose up -d pulse - ``` -5. Access the application at http://localhost:7654 - -### Quick Start with Docker Hub - -The easiest way to get started with Pulse is to use the pre-built Docker image: - -1. Create a `.env` file with your ProxMox node details (see Configuration section) -2. Run the container: - ```bash - docker run -d -p 7654:7654 --env-file .env --name pulse-app rcourtman/pulse:latest - ``` -3. Access the application at http://localhost:7654 - -## Docker Details - -The Docker setup uses a production-optimized build that: -- Runs the compiled application with minimal dependencies -- Runs as a non-root user for better security -- Serves both frontend and backend on port 7654 -- Exits if startup checks fail (e.g., if it can't connect to your ProxMox nodes) - -For development, use `./start-dev.sh` instead of Docker, as it provides: -- Hot-reloading of both frontend and backend -- Source maps for better debugging -- Development tools and detailed logging -- Immediate reflection of code changes - -## Configuration - -The only configuration you need to provide is your ProxMox node details. Create a `.env` file in the root directory based on the `.env.example` file: - -``` -# ProxMox Node Configuration -# Replace with your ProxMox node details - -# Node 1 -PROXMOX_NODE_1_NAME=Proxmox Node 1 -PROXMOX_NODE_1_HOST=https://proxmox.local:8006 -PROXMOX_NODE_1_TOKEN_ID=root@pam!pulse -PROXMOX_NODE_1_TOKEN_SECRET=your-token-secret - -# Node 2 (optional) -PROXMOX_NODE_2_NAME=Proxmox Node 2 -PROXMOX_NODE_2_HOST=https://proxmox2.local:8006 -PROXMOX_NODE_2_TOKEN_ID=root@pam!pulse -PROXMOX_NODE_2_TOKEN_SECRET=your-token-secret -``` - -### Advanced Configuration - -You can customize the application further with these optional settings: - -``` -# App Configuration (usually you don't need to change these) -PORT=7654 -NODE_ENV=development -LOG_LEVEL=debug -ENABLE_DEV_TOOLS=true -METRICS_HISTORY_MINUTES=60 -IGNORE_SSL_ERRORS=true -NODE_TLS_REJECT_UNAUTHORIZED=0 - -# Polling Intervals (in milliseconds) -NODE_POLLING_INTERVAL_MS=2000 -EVENT_POLLING_INTERVAL_MS=1000 -``` - -The application is optimized for maximum responsiveness with polling intervals of 2000ms for nodes and 1000ms for events. For environments with limited resources, you may want to increase these values. - -The `NODE_TLS_REJECT_UNAUTHORIZED=0` setting is particularly important when using self-signed certificates, as it tells Node.js to ignore SSL certificate validation errors. Note that this should only be used in development environments or when you trust your network, as it bypasses security checks. - -### Important Note on API Tokens - -If your ProxMox API token ID contains special characters (like `!`, `@`, or `%`), make sure to properly encode them in your environment variables. In some cases, you may need to escape these characters or enclose the entire token ID in quotes. - -For example: -``` -PROXMOX_NODE_1_TOKEN_ID="root@pam!pulse" -``` - ## Troubleshooting -### Common Development Issues +### Development Issues #### Port Conflicts -If you see "Port already in use" errors: -1. Use `npm run dev:kill:all` to stop all development servers -2. Check if any other applications are using ports 3000 or 7654 -3. Restart the development server with `npm run dev:start` +```bash +# Kill all development servers and try again +npm run dev:kill:all +./start-dev.sh +``` #### Connection Issues -If you see connection errors: -1. Verify your ProxMox node details in `.env` are correct -2. Run `npm run test:api` to test the ProxMox API connection -3. Check if your ProxMox node is accessible from your machine -4. For SSL issues, ensure `IGNORE_SSL_ERRORS` and `NODE_TLS_REJECT_UNAUTHORIZED` are set correctly for your environment +1. Verify your ProxMox node details in `.env` +2. Run `npm run test:api` to test the connection +3. Check if your ProxMox node is accessible +4. For SSL issues in development, set: + ``` + IGNORE_SSL_ERRORS=true + NODE_TLS_REJECT_UNAUTHORIZED=0 + ``` #### Hot Reload Not Working -1. Ensure you're accessing the frontend via http://localhost:3000 in development -2. Check if both frontend and backend servers are running (`npm run dev:start` starts both) -3. Clear your browser cache and reload the page - -### Common Production Issues - -#### Docker Container Not Starting -1. Check container logs: `docker logs pulse-app` -2. Verify your `.env` file is properly mounted -3. Ensure port 7654 is not in use by another application -4. Run `docker-compose logs pulse` to see detailed logs - -#### SSL/TLS Issues -1. For production, ensure you have valid SSL certificates -2. Set `IGNORE_SSL_ERRORS=false` and `NODE_TLS_REJECT_UNAUTHORIZED=1` -3. If using self-signed certificates, they must be properly installed and trusted - -#### Version Mismatch -If the displayed version doesn't match the latest release: -1. Pull the latest Docker image: `docker pull rcourtman/pulse:latest` -2. Restart the container with the new image -3. Clear your browser cache - -For additional support or unresolved issues, please open an issue on the [GitHub repository](https://github.com/rcourtman/pulse/issues). +1. Ensure you're using http://localhost:3000 +2. Kill all servers and restart: + ```bash + npm run dev:kill:all + ./start-dev.sh + ``` ## Contributing -We welcome contributions from the community! Here's how you can help: - -### Development Workflow - 1. Fork the repository -2. Create a feature branch: - ```bash - git checkout -b feature/your-feature-name - ``` -3. Set up your development environment: - ```bash - npm install - cd frontend && npm install - ``` -4. Make your changes following our coding standards: - - Use TypeScript for type safety - - Follow ESLint rules (`npm run lint`) - - Add comments for complex logic - - Update tests if applicable - -5. Test your changes: - - Run the application in development mode - - Test both frontend and backend functionality - - Verify changes in both development and production modes - -6. Submit a Pull Request: - - Provide a clear description of the changes - - Reference any related issues - - Include screenshots for UI changes - - Ensure all checks pass - -### Code Style Guidelines - -- Use TypeScript for all new code -- Follow the existing project structure -- Use meaningful variable and function names -- Add JSDoc comments for public APIs -- Keep components and functions focused and small -- Write self-documenting code where possible - -### Reporting Issues - -When reporting issues, please include: -- Your environment details (OS, Node.js version, etc.) -- Steps to reproduce the issue -- Expected vs actual behavior -- Relevant error messages and logs -- Screenshots if applicable - -## Performance Tuning - -### Polling Intervals -Adjust these settings in your `.env` file based on your needs: -```bash -# For maximum responsiveness (high update frequency) -NODE_POLLING_INTERVAL_MS=2000 # Default: 2000 (2 seconds) -EVENT_POLLING_INTERVAL_MS=1000 # Default: 1000 (1 second) - -# For balanced performance (medium update frequency) -NODE_POLLING_INTERVAL_MS=5000 # 5 seconds -EVENT_POLLING_INTERVAL_MS=2000 # 2 seconds - -# For minimal server load (less frequent updates) -NODE_POLLING_INTERVAL_MS=30000 # 30 seconds -EVENT_POLLING_INTERVAL_MS=5000 # 5 seconds - -# Adjust metrics history for memory usage optimization -METRICS_HISTORY_MINUTES=60 # Default: 60 minutes -``` - -### WebSocket Configuration -The application uses optimized WebSocket settings for real-time updates: - -- **Backend WebSocket**: - - `pingTimeout`: 15000ms (15 seconds) - - `pingInterval`: 2000ms (2 seconds, matches node polling) - - `perMessageDeflate`: Enabled with threshold at 512 bytes - -- **Frontend Socket.io Client**: - - Primary transport: WebSockets with polling fallback - - Reconnection attempts: 20 - - Connection recovery: Enabled for up to 2 minutes of disconnection - -### Resource Usage Guidelines -- Memory usage scales with: - - Number of ProxMox nodes - - Number of VMs/containers - - Metrics history length - - Polling frequency - -### Optimization Tips -1. **For Maximum Responsiveness**: - - Use the lowest polling intervals (2000ms/1000ms) - - Ensure your server has adequate CPU resources - - Maintain a stable network connection between the app and Proxmox - - Use a modern browser with WebSocket support - -2. **High-Traffic Environments**: - - Increase polling intervals - - Reduce metrics history - - Use a reverse proxy with caching - - Consider running multiple instances - -3. **Low-Resource Environments**: - - Reduce WebSocket connections - - Increase polling intervals - - Reduce metrics history - -## Security Best Practices - -### API Token Security -- Create a dedicated API token for Pulse with minimal permissions (PVEAuditor only) -- Never use root tokens or tokens with write permissions -- Rotate API tokens periodically -- Use environment variables or secrets management in production -- Never commit API tokens to version control - -### Network Security -- Run behind a reverse proxy in production -- Use HTTPS for all ProxMox connections -- Enable SSL certificate validation in production -- Restrict access to the dashboard using network controls -- Consider using VPN for remote access - -### Docker Security -- Never run the container as root -- Keep the Docker image updated -- Use Docker secrets or environment files for sensitive data -- Regularly update base images and dependencies -- Scan container images for vulnerabilities - -### Development Security -- Keep all dependencies updated -- Run `npm audit` regularly -- Use `.env.example` without real credentials -- Never expose development ports to the internet -- Use different API tokens for development and production - -⚠️ **Important Security Notes**: -1. This tool is for monitoring only and should never have write access to your ProxMox cluster -2. Development security settings (`IGNORE_SSL_ERRORS=true`) bypass important security checks -3. Always validate SSL certificates in production environments -4. Restrict access to the monitoring interface to trusted networks/users - -## Monitoring and Maintenance - -### Health Checks - -#### Application Health -Monitor these indicators for application health: -```bash -# Check application status -curl http://localhost:7654/health - -# Check WebSocket connectivity -curl http://localhost:7654/health/ws - -# Verify ProxMox connectivity -npm run test:api -``` - -#### Container Health -For Docker deployments: -```bash -# View container status -docker ps -a | grep pulse-app - -# Check container health -docker inspect pulse-app | grep Health - -# View resource usage -docker stats pulse-app - -# Check container logs -docker logs -f --tail 100 pulse-app -``` - -### Regular Maintenance - -#### Weekly Tasks -1. Check for updates: - ```bash - docker pull rcourtman/pulse:latest - ``` -2. Review logs for errors -3. Verify API token permissions -4. Monitor resource usage trends - -#### Monthly Tasks -1. Rotate API tokens -2. Update SSL certificates if needed -3. Review security settings -4. Backup configuration files - -#### Update Procedure -1. Backup your configuration: - ```bash - cp .env .env.backup - ``` -2. Pull latest version: - ```bash - docker pull rcourtman/pulse:latest - ``` -3. Stop current container: - ```bash - docker stop pulse-app - docker rm pulse-app - ``` -4. Start new container: - ```bash - docker run -d -p 7654:7654 --env-file .env --name pulse-app rcourtman/pulse:latest - ``` -5. Verify application status: - ```bash - curl http://localhost:7654/health - ``` - -### Logging - -#### Log Levels -Configure logging based on your needs: -```bash -# Production (minimal logging) -LOG_LEVEL=error - -# Debugging (detailed logging) -LOG_LEVEL=debug -``` - -#### Log Rotation -For production deployments, configure log rotation: -```bash -# Docker log rotation -docker run -d \ - --log-driver json-file \ - --log-opt max-size=10m \ - --log-opt max-file=3 \ - --name pulse-app \ - rcourtman/pulse:latest -``` - -### Backup and Recovery - -#### Configuration Backup -Regularly backup these files: -- `.env` file -- `docker-compose.yml` -- Custom SSL certificates -- Any custom configurations - -#### Recovery Procedure -1. Stop the container: - ```bash - docker stop pulse-app - ``` -2. Restore configuration: - ```bash - cp .env.backup .env - ``` -3. Restart with backup config: - ```bash - docker start pulse-app - ``` - -## Support - -If you encounter any issues or have questions, please open an issue on the [GitHub repository](https://github.com/rcourtman/pulse/issues). +2. Create a feature branch +3. Set up development environment +4. Make your changes +5. Test thoroughly +6. Submit a Pull Request ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. - -## Acknowledgments - -- Thanks to the ProxMox team for their excellent virtualization platform -- All contributors who have helped improve this project \ No newline at end of file +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml deleted file mode 100644 index 353aaff43..000000000 --- a/docker-compose.yml +++ /dev/null @@ -1,25 +0,0 @@ -services: - # Production service - pulse: - build: - context: . - target: production - args: - NODE_ENV: production - LOG_LEVEL: info - ENABLE_DEV_TOOLS: 'false' - PORT: 7654 - container_name: pulse-app - ports: - - "7654:7654" - restart: unless-stopped - env_file: - - .env - volumes: - - ./logs:/app/logs - healthcheck: - test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:7654/health"] - interval: 30s - timeout: 10s - retries: 3 - start_period: 10s \ No newline at end of file diff --git a/publish-docker.sh b/publish-docker.sh deleted file mode 100755 index 3cf536188..000000000 --- a/publish-docker.sh +++ /dev/null @@ -1,52 +0,0 @@ -#!/bin/bash - -# Script to build and push Docker images for Pulse to Docker Hub -# Usage: ./publish-docker.sh -# Example: ./publish-docker.sh 1.0.0 - -# Exit on error -set -e - -# Check if version is provided -if [ -z "$1" ]; then - echo "Error: Version number is required" - echo "Usage: ./publish-docker.sh " - echo "Example: ./publish-docker.sh 1.0.0" - exit 1 -fi - -VERSION=$1 -USERNAME="rcourtman" -REPO="pulse" - -echo "🔨 Building Docker image for $USERNAME/$REPO:$VERSION..." -docker build -t $USERNAME/$REPO:$VERSION --target production . - -echo "🏷️ Tagging additional versions..." -# Tag as latest -docker tag $USERNAME/$REPO:$VERSION $USERNAME/$REPO:latest - -# Tag as major.minor (e.g., 1.0) -MAJOR_MINOR=$(echo $VERSION | cut -d. -f1,2) -docker tag $USERNAME/$REPO:$VERSION $USERNAME/$REPO:$MAJOR_MINOR - -echo "🔑 Logging in to Docker Hub..." -echo "Please enter your Docker Hub password when prompted" -docker login -u $USERNAME - -echo "⬆️ Pushing images to Docker Hub..." -docker push $USERNAME/$REPO:$VERSION -docker push $USERNAME/$REPO:latest -docker push $USERNAME/$REPO:$MAJOR_MINOR - -echo "✅ Successfully published $USERNAME/$REPO:$VERSION to Docker Hub!" -echo "✅ Also published tags: latest, $MAJOR_MINOR" -echo "" -echo "Users can now pull your image with:" -echo "docker pull $USERNAME/$REPO:$VERSION" -echo "" -echo "Or use the latest version:" -echo "docker pull $USERNAME/$REPO:latest" -echo "" -echo "Run with:" -echo "docker run -d -p 7654:7654 --env-file .env --name pulse-app $USERNAME/$REPO:latest" \ No newline at end of file