gsadmin/pulse
1
0
Fork 0
mirror of https://github.com/rcourtman/Pulse.git synced 2026-09-10 18:45:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Simplify repository: Remove GitHub workflows and simplify Docker for production only

Browse Source 
- Remove GitHub workflows and related files

- Simplify Dockerfile to focus on production build only

- Update README to focus on local development with Docker for production

- Remove docker-compose and other Docker-related files

- Clean up documentation to match new simplified approach
This commit is contained in:
courtmanr@gmail.com
2025-03-03 15:18:55 +00:00
parent 7716d0ad37
commit 770fe7cb24
10 changed files with 79 additions and 1010 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.dockerignore
-37
View File
@@ -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
.github/FUNDING.yml
-13
View File
@@ -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']
.github/ISSUE_TEMPLATE/docker-issue.md
-36
View File
@@ -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:**
<!-- Which version of the Docker image are you using? (e.g., rcourtman/pulse:1.0.0) -->
**Environment:**
<!-- Details about your environment (OS, Docker version, etc.) -->
**Issue Description:**
<!-- A clear description of the issue you're experiencing -->
**Steps to Reproduce:**
<!-- Steps to reproduce the behavior -->
**Expected Behavior:**
<!-- What you expected to happen -->
**Actual Behavior:**
<!-- What actually happened -->
**Docker Run Command:**
<!-- The command you used to run the container -->
```bash
docker run -d -p 7654:7654 --env-file .env --name pulse-app rcourtman/pulse:latest
```
**Additional Context:**
<!-- Any other context about the problem here -->
.github/workflows/README.md
-29
View File
@@ -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
.github/workflows/docker-publish.yml.disabled
-60
View File
@@ -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
.github/workflows/update-version.yml.disabled
-41
View File
@@ -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)
Dockerfile
+7 -73
View File
@@ -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"]
CMD ["node", "dist/server.js"]
README.md
+72 -644
View File
@@ -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
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
docker-compose.yml
-25
View File
@@ -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
publish-docker.sh
-52
View File
@@ -1,52 +0,0 @@
#!/bin/bash
# Script to build and push Docker images for Pulse to Docker Hub
# Usage: ./publish-docker.sh <version>
# 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 <version>"
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"