diff --git a/README.md b/README.md index d0abd04..b052869 100644 --- a/README.md +++ b/README.md @@ -1,362 +1,54 @@ # SkyWatch -A comprehensive monitoring system for tracking the uptime and performance of your ZimaOS server and other online resources. +A comprehensive monitoring system for tracking the uptime and performance of your resources. ## Features - 📊 **Real-time Dashboard** - Monitor all your resources at a glance -- 📈 **Performance Graphs** - Visualize response times and uptime statistics +- 📈 **Performance Graphs** - Visualize response times and uptime statistics with intelligent averaging - 🔔 **Alert Notifications** - Email and webhook alerts when resources go offline - 📝 **Incident Tracking** - Track when resources go down and recover - ⚙️ **Configurable Checks** - Set custom check intervals and timeouts - 🗄️ **Historical Data** - 7 days of check history with detailed statistics -## Installation +## Quick Start -### Quick Install on Ubuntu (One Command) +### Installation +See [Installation Guide](docs/INSTALLATION.md) for detailed setup instructions. + +**Quick Install on Ubuntu:** ```bash curl -fsSL https://raw.githubusercontent.com/nmemmert/monitor/main/install-ubuntu.sh | bash ``` -The script will: -- ✅ Install Node.js 20.x -- ✅ Install PM2 process manager -- ✅ Clone and set up the application -- ✅ Configure firewall -- ✅ Set up auto-start on boot -- ✅ Guide you through email/webhook setup +### First Steps -### Manual Installation +1. [Install SkyWatch](docs/INSTALLATION.md) +2. [Deploy to Your Server](docs/DEPLOYMENT.md) +3. [Learn How to Use](docs/USAGE.md) -#### Prerequisites +## Documentation -- Node.js (v14 or higher) -- npm or yarn +| Topic | Description | +|-------|-------------| +| [📦 Installation](docs/INSTALLATION.md) | Quick install, manual setup, dev/prod modes | +| [🚀 Deployment](docs/DEPLOYMENT.md) | Deploy to remote servers, Docker, services, firewall | +| [📚 Usage Guide](docs/USAGE.md) | Dashboard, History, Settings, Resources, SLA Reports | +| [🆘 Troubleshooting](docs/TROUBLESHOOTING.md) | Common issues and solutions | -#### Setup +## History Feature -1. Install dependencies for both server and client: -```bash -npm run install-all -``` +The History page shows detailed check data with two viewing modes: -2. Create a `.env` file in the root directory (copy from `.env.example`): -```bash -cp .env.example .env -``` +- **Averaged Mode** (Default) - Server-side bucketing for fast, clean graphs + - 7 Days: 1-hour buckets + - 14 Days: 3-hour buckets + - 30 Days: 6-hour buckets -3. Configure your `.env` file: -```env -PORT=3001 +- **Raw Mode** - Up to 600 individual checks for detailed analysis -# Email Notifications (optional) -EMAIL_ENABLED=true -EMAIL_HOST=smtp.gmail.com -EMAIL_PORT=587 -EMAIL_USER=your-email@gmail.com -EMAIL_PASS=your-app-password -EMAIL_FROM=your-email@gmail.com -EMAIL_TO=your-email@gmail.com - -# Webhook Notifications (optional) -WEBHOOK_ENABLED=false -WEBHOOK_URL=https://your-webhook-url.com -``` - -## Usage - -### Development Mode - -Run both server and client in development mode: -```bash -npm run dev -``` - -- Server runs on http://localhost:3001 -- Client runs on http://localhost:3000 - -### Production Mode - -Build and run in production: -```bash -npm run build -npm start -``` - -Server will serve the built React app on http://localhost:3001 - -## Deploying to a Remote Computer - -### Option 1: Direct Copy (Simplest) - -1. **On your local machine:** -```bash -# Build the React app -cd client -npm run build -cd .. - -# Create a deployment package -# Copy these folders/files to remote: -# - server/ -# - client/build/ -# - data/ (optional, will be created if missing) -# - package.json -# - .env.example -``` - -2. **On the remote computer:** -```bash -# Install Node.js if not already installed -# Copy the files to a directory (e.g., /opt/resource-monitor or C:\monitor) - -# Install dependencies -npm install - -# Copy .env.example to .env and configure -cp .env.example .env -nano .env # or use notepad on Windows - -# Set NODE_ENV to production -# Add to .env: NODE_ENV=production - -# Start the server -npm start -``` - -3. **Access the dashboard:** - - Visit `http://your-remote-ip:3001` - -### Option 2: Git Repository (Best Practice) - -1. **Initialize git and push to repository:** -```bash -git init -git add . -git commit -m "Initial commit" -git remote add origin your-git-repo-url -git push -u origin main -``` - -2. **On remote computer:** -```bash -git clone your-git-repo-url -cd resource-monitor -npm run install-all -cd client && npm run build && cd .. -cp .env.example .env -nano .env # Configure your settings -npm start -``` - -### Option 3: Docker Deployment (Advanced) - -Create `Dockerfile` in project root: -```dockerfile -FROM node:18 -WORKDIR /app -COPY package*.json ./ -RUN npm install -COPY . . -WORKDIR /app/client -RUN npm install && npm run build -WORKDIR /app -EXPOSE 3001 -CMD ["node", "server/index.js"] -``` - -Then deploy: -```bash -docker build -t resource-monitor . -docker run -d -p 3001:3001 -v ./data:/app/data --name monitor resource-monitor -``` - -### Deployment Workflow (Critical!) - -**⚠️ IMPORTANT: Always use `npm run build:commit` when deploying changes:** - -```bash -# Make your code changes -npm run build:commit # This builds React AND commits the build files to git -# Or manually: -npm run build -git add -f client/build/ -git commit -m "Update build files" -git push - -# Then on remote server: -cd /opt/resource-monitor -git pull -pm2 restart monitor -# Hard-refresh browser (Ctrl+Shift+R) to clear cache -``` - -**Why?** The React build creates new bundle file hashes each time. If you don't commit the build files: -- ❌ Old cached HTML points to old JS bundle hashes -- ❌ New JS files aren't in git, so remote server gets old builds -- ❌ White screen / script loading errors - -**Solution:** Always commit build files to git before deploying! - -### Running as a Service (Keep it Running) - -**Linux (systemd):** -Create `/etc/systemd/system/skywatch.service`: -```ini -[Unit] -Description=SkyWatch -After=network.target - -[Service] -Type=simple -User=youruser -WorkingDirectory=/opt/skywatch -ExecStart=/usr/bin/node server/index.js -Restart=always -Environment=NODE_ENV=production - -[Install] -WantedBy=multi-user.target -``` - -Enable and start: -```bash -sudo systemctl enable resource-monitor -sudo systemctl start resource-monitor -``` - -**Windows (NSSM - Non-Sucking Service Manager):** -```powershell -# Download NSSM from nssm.cc -nssm install ResourceMonitor "C:\Program Files\nodejs\node.exe" -nssm set ResourceMonitor AppDirectory "C:\monitor" -nssm set ResourceMonitor AppParameters "server\index.js" -nssm start ResourceMonitor -``` - -**Using PM2 (Cross-platform):** -```bash -# Install PM2 globally -npm install -g pm2 - -# Start the application -pm2 start server/index.js --name resource-monitor - -# Save the process list -pm2 save - -# Set PM2 to start on boot -pm2 startup -``` - -### Firewall Configuration - -Make sure port 3001 is accessible: - -**Linux (UFW):** -```bash -sudo ufw allow 3001/tcp -``` - -**Windows:** -```powershell -New-NetFirewallRule -DisplayName "SkyWatch" -Direction Inbound -LocalPort 3001 -Protocol TCP -Action Allow -``` - -### Reverse Proxy (Optional but Recommended) - -Use Nginx to serve on port 80/443: - -```nginx -server { - listen 80; - server_name your-domain.com; - - location / { - proxy_pass http://localhost:3001; - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection 'upgrade'; - proxy_set_header Host $host; - proxy_cache_bypass $http_upgrade; - } -} -``` - -### Configuring Notifications (Setup Wizard) - -1. Navigate to **Settings** in the top navigation -2. Configure email notifications: - - Toggle "Email Notifications" on - - Select your email provider (Gmail, Outlook, Yahoo, or Custom) - - Enter your email credentials - - **For Gmail**: Use an App Password (see instructions in the UI) - - Click "Send Test Email" to verify -3. Configure webhook notifications (optional): - - Toggle "Webhook Notifications" on - - Enter your webhook URL (Slack, Discord, etc.) - - Click "Send Test Webhook" to verify -4. Click "Save Settings" - -### Adding Resources - -1. Click "Add Resource" on the dashboard -2. Enter resource details: - - **Name**: Friendly name (e.g., "ZimaOS Home Server") - - **URL**: Full URL to monitor (e.g., "https://your-zima.example.com") - - **Check Interval**: How often to check (in milliseconds) - - **Timeout**: Maximum time to wait for response - -### Viewing History - -The **History** page displays detailed check data for all monitored resources with interactive graphs and performance metrics. - -#### Time Window Selection - -- **7 Days** - Default view, showing hourly averages (168 data points) -- **14 Days** - Shows 3-hourly averages (112 data points) -- **30 Days** - Shows 6-hourly averages (120 data points) - -#### Show Averages Toggle - -The **"Show Averages"** checkbox controls how data is displayed: - -**When Enabled (Default):** -- Data is **bucketed and averaged** server-side -- 7 Days: 1-hour buckets (168 points) -- 14 Days: 3-hour buckets (112 points) -- 30 Days: 6-hour buckets (120 points) -- **Benefit**: Much faster page load, cleaner graphs with averaged response times -- **Use when**: Viewing trends over time - -**When Disabled:** -- Shows up to 600 **raw individual checks** within the selected time window -- **Benefit**: See exact check-by-check performance, spot patterns -- **Use when**: Debugging specific issues, investigating downtime events - -#### Graph Display - -Each resource shows: -- **Response Time (Blue Line)** - Average response time in milliseconds -- **Status Bars (Green/Red)** - - - 🟢 Green = Resource was UP during that period - - 🔴 Red = Resource was DOWN during that period - -#### Statistics - -Below each graph: -- **Total Checks** - Number of checks performed in the time window -- **Uptime %** - Percentage of checks that were successful (green = higher is better) -- **Avg Response** - Average response time in milliseconds -- **Successful Checks** - Count of successful vs total checks (e.g., 5592/5593) - -#### Performance Notes - -- **Averaged mode** is optimized for performance and uses server-side aggregation -- **Non-averaged mode** can be slower with large datasets (>600 checks) -- Cache is updated every 2 minutes for averaged data -- Each time window (7/14/30 days) has separate cache entries +See [Usage Guide → History Page](docs/USAGE.md#history-page) for details. ## API Endpoints @@ -379,45 +71,20 @@ mon/ │ ├── notificationService.js │ └── scheduler.js ├── client/ # React frontend -│ └── src/ -│ ├── App.js # Main React component -│ └── App.css # Styles +│ ├── src/ +│ │ ├── App.js # Main React component +│ │ ├── History.js # History page with graphs +│ │ └── App.css # Styles +│ └── build/ # Production bundle (committed to git) +├── docs/ # Documentation ├── data/ # SQLite database (auto-created) ├── .env # Environment configuration └── package.json ``` -## Configuration +## Support -### Check Intervals - -The monitoring system checks all enabled resources every minute. You can customize individual resource check intervals through the UI. - -### Data Retention - -- Check history: 7 days -- Incidents: Indefinitely (manual cleanup) - -## Troubleshooting - -### Port Already in Use - -If port 3001 is already in use, change it in `.env`: -```env -PORT=3002 -``` - -### Email Not Sending - -- Verify SMTP credentials -- Check that 2FA is enabled and app password is used -- Test with a simple SMTP client first - -### Resource Not Being Checked - -- Verify resource is enabled -- Check server logs for errors -- Ensure URL is accessible from server +Having issues? Check the [Troubleshooting Guide](docs/TROUBLESHOOTING.md) for solutions to common problems. ## License diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md new file mode 100644 index 0000000..084ca55 --- /dev/null +++ b/docs/DEPLOYMENT.md @@ -0,0 +1,201 @@ +# Deployment Guide + +## Option 1: Direct Copy (Simplest) + +1. **On your local machine:** +```bash +# Build the React app +cd client +npm run build +cd .. + +# Create a deployment package +# Copy these folders/files to remote: +# - server/ +# - client/build/ +# - data/ (optional, will be created if missing) +# - package.json +# - .env.example +``` + +2. **On the remote computer:** +```bash +# Install Node.js if not already installed +# Copy the files to a directory (e.g., /opt/resource-monitor or C:\monitor) + +# Install dependencies +npm install + +# Copy .env.example to .env and configure +cp .env.example .env +nano .env # or use notepad on Windows + +# Set NODE_ENV to production +# Add to .env: NODE_ENV=production + +# Start the server +npm start +``` + +3. **Access the dashboard:** + - Visit `http://your-remote-ip:3001` + +## Option 2: Git Repository (Best Practice) + +1. **Initialize git and push to repository:** +```bash +git init +git add . +git commit -m "Initial commit" +git remote add origin your-git-repo-url +git push -u origin main +``` + +2. **On remote computer:** +```bash +git clone your-git-repo-url +cd resource-monitor +npm run install-all +cd client && npm run build && cd .. +cp .env.example .env +nano .env # Configure your settings +npm start +``` + +## Option 3: Docker Deployment (Advanced) + +Create `Dockerfile` in project root: +```dockerfile +FROM node:18 +WORKDIR /app +COPY package*.json ./ +RUN npm install +COPY . . +WORKDIR /app/client +RUN npm install && npm run build +WORKDIR /app +EXPOSE 3001 +CMD ["node", "server/index.js"] +``` + +Then deploy: +```bash +docker build -t resource-monitor . +docker run -d -p 3001:3001 -v ./data:/app/data --name monitor resource-monitor +``` + +## Deployment Workflow (Critical!) + +**⚠️ IMPORTANT: Always commit build files when deploying changes:** + +```bash +# Make your code changes +npm run build +git add -f client/build/ +git commit -m "Update build files" +git push + +# Then on remote server: +cd /opt/resource-monitor +git pull +pm2 restart monitor +# Hard-refresh browser (Ctrl+Shift+R) to clear cache +``` + +### Why? + +The React build creates new bundle file hashes each time. If you don't commit the build files: +- ❌ Old cached HTML points to old JS bundle hashes +- ❌ New JS files aren't in git, so remote server gets old builds +- ❌ White screen / script loading errors + +### Solution: +Always commit build files to git before deploying! + +## Running as a Service (Keep it Running) + +### Linux (systemd) + +Create `/etc/systemd/system/skywatch.service`: +```ini +[Unit] +Description=SkyWatch +After=network.target + +[Service] +Type=simple +User=youruser +WorkingDirectory=/opt/skywatch +ExecStart=/usr/bin/node server/index.js +Restart=always +Environment=NODE_ENV=production + +[Install] +WantedBy=multi-user.target +``` + +Enable and start: +```bash +sudo systemctl enable resource-monitor +sudo systemctl start resource-monitor +``` + +### Windows (NSSM - Non-Sucking Service Manager) + +```powershell +# Download NSSM from nssm.cc +nssm install ResourceMonitor "C:\Program Files\nodejs\node.exe" +nssm set ResourceMonitor AppDirectory "C:\monitor" +nssm set ResourceMonitor AppParameters "server\index.js" +nssm start ResourceMonitor +``` + +### Cross-platform (PM2) + +```bash +# Install PM2 globally +npm install -g pm2 + +# Start the application +pm2 start server/index.js --name resource-monitor + +# Save the process list +pm2 save + +# Set PM2 to start on boot +pm2 startup +``` + +## Firewall Configuration + +Make sure port 3001 is accessible: + +### Linux (UFW) +```bash +sudo ufw allow 3001/tcp +``` + +### Windows +```powershell +New-NetFirewallRule -DisplayName "SkyWatch" -Direction Inbound -LocalPort 3001 -Protocol TCP -Action Allow +``` + +## Reverse Proxy (Optional but Recommended) + +Use Nginx to serve on port 80/443: + +```nginx +server { + listen 80; + server_name your-domain.com; + + location / { + proxy_pass http://localhost:3001; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection 'upgrade'; + proxy_set_header Host $host; + proxy_cache_bypass $http_upgrade; + } +} +``` diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md new file mode 100644 index 0000000..651ae17 --- /dev/null +++ b/docs/INSTALLATION.md @@ -0,0 +1,72 @@ +# Installation Guide + +## Quick Install on Ubuntu (One Command) + +```bash +curl -fsSL https://raw.githubusercontent.com/nmemmert/monitor/main/install-ubuntu.sh | bash +``` + +The script will: +- ✅ Install Node.js 20.x +- ✅ Install PM2 process manager +- ✅ Clone and set up the application +- ✅ Configure firewall +- ✅ Set up auto-start on boot +- ✅ Guide you through email/webhook setup + +## Manual Installation + +### Prerequisites + +- Node.js (v14 or higher) +- npm or yarn + +### Setup + +1. Install dependencies for both server and client: +```bash +npm run install-all +``` + +2. Create a `.env` file in the root directory (copy from `.env.example`): +```bash +cp .env.example .env +``` + +3. Configure your `.env` file: +```env +PORT=3001 + +# Email Notifications (optional) +EMAIL_ENABLED=true +EMAIL_HOST=smtp.gmail.com +EMAIL_PORT=587 +EMAIL_USER=your-email@gmail.com +EMAIL_PASS=your-app-password +EMAIL_FROM=your-email@gmail.com +EMAIL_TO=your-email@gmail.com + +# Webhook Notifications (optional) +WEBHOOK_ENABLED=false +WEBHOOK_URL=https://your-webhook-url.com +``` + +## Development Mode + +Run both server and client in development mode: +```bash +npm run dev +``` + +- Server runs on http://localhost:3001 +- Client runs on http://localhost:3000 + +## Production Mode + +Build and run in production: +```bash +npm run build +npm start +``` + +Server will serve the built React app on http://localhost:3001 diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000..4412c2c --- /dev/null +++ b/docs/TROUBLESHOOTING.md @@ -0,0 +1,86 @@ +# Troubleshooting Guide + +## Port Already in Use + +If port 3001 is already in use, change it in `.env`: +```env +PORT=3002 +``` + +Then restart the server. + +## Email Not Sending + +- Verify SMTP credentials are correct +- Check that 2FA is enabled and you're using an app password (for Gmail) +- Test with a simple SMTP client first +- Check server logs for specific error messages +- Verify EMAIL_ENABLED=true in .env +- Ensure EMAIL_TO is set to a valid email address + +## Resource Not Being Checked + +- Verify resource is enabled (toggle in dashboard) +- Check server logs for errors with `pm2 logs resource-monitor` +- Ensure URL is accessible from the server (try `curl https://url` from server) +- Verify the resource type matches (http, https, ping, etc.) +- Check that the check interval is set to a reasonable value + +## White Screen on Load + +- Hard refresh browser (Ctrl+Shift+R on Windows, Cmd+Shift+R on Mac) +- Clear browser cache +- Check console for JavaScript errors (F12 → Console) +- Verify build files are in `client/build/` directory +- Make sure you committed build files before deploying + +## History Page Slow + +- Toggle off "Show Averages" if viewing large time windows +- Use the 7-day view instead of 30 days +- Check server load with `pm2 monit` +- Increase server resources if needed + +## Database Issues + +- Check that `/opt/resource-monitor/data/` directory exists and is writable +- Verify database file permissions: `ls -la data/skywatch.db` +- If corrupted, delete database and restart to rebuild from scratch + +## Memory Issues + +- Monitor with `pm2 monit` +- Check cache size with GET `/api/cache/clear` endpoint +- Reduce data retention period +- Enable auto-cleanup in settings + +## Connection Refused + +- Verify server is running: `pm2 list` +- Check port is correct: `netstat -an | grep 3001` (Linux) or `netstat -ano | findstr 3001` (Windows) +- Check firewall rules allow port 3001 +- Verify .env PORT setting matches + +## Incidents Not Triggering + +- Verify consecutive_failures threshold is met (default: 3) +- Check grace_period setting (default: 300 seconds) +- Review alert settings in Settings page +- Check notification service is enabled +- View server logs: `pm2 logs resource-monitor` + +## API Endpoints Not Working + +- Verify server is running on correct port +- Check CORS settings if accessing from different domain +- Review request method (GET vs POST) +- Check error response for specific error message +- Verify request parameters are correct + +## Performance Issues + +- Use averaged mode in history (default is enabled) +- Increase check intervals for resources +- Enable caching (default is 2 minutes) +- Consider archiving old data +- Monitor database size: `ls -lh data/skywatch.db` diff --git a/docs/USAGE.md b/docs/USAGE.md new file mode 100644 index 0000000..179d90e --- /dev/null +++ b/docs/USAGE.md @@ -0,0 +1,96 @@ +# Usage Guide + +## Dashboard + +The main dashboard provides a real-time overview of all monitored resources with their current status, uptime, and response times. + +## History Page + +The **History** page displays detailed check data for all monitored resources with interactive graphs and performance metrics. + +### Time Window Selection + +- **7 Days** - Default view, showing hourly averages (168 data points) +- **14 Days** - Shows 3-hourly averages (112 data points) +- **30 Days** - Shows 6-hourly averages (120 data points) + +### Show Averages Toggle + +The **"Show Averages"** checkbox controls how data is displayed: + +#### When Enabled (Default) +- Data is **bucketed and averaged** server-side +- 7 Days: 1-hour buckets (168 points) +- 14 Days: 3-hour buckets (112 points) +- 30 Days: 6-hour buckets (120 points) +- **Benefit**: Much faster page load, cleaner graphs with averaged response times +- **Use when**: Viewing trends over time + +#### When Disabled +- Shows up to 600 **raw individual checks** within the selected time window +- **Benefit**: See exact check-by-check performance, spot patterns +- **Use when**: Debugging specific issues, investigating downtime events + +### Graph Display + +Each resource shows: +- **Response Time (Blue Line)** - Average response time in milliseconds +- **Status Bars (Green/Red)** - + - 🟢 Green = Resource was UP during that period + - 🔴 Red = Resource was DOWN during that period + +### Statistics + +Below each graph: +- **Total Checks** - Number of checks performed in the time window +- **Uptime %** - Percentage of checks that were successful (green = higher is better) +- **Avg Response** - Average response time in milliseconds +- **Successful Checks** - Count of successful vs total checks (e.g., 5592/5593) + +### Performance Notes + +- **Averaged mode** is optimized for performance and uses server-side aggregation +- **Non-averaged mode** can be slower with large datasets (>600 checks) +- Cache is updated every 2 minutes for averaged data +- Each time window (7/14/30 days) has separate cache entries + +## Settings Page + +Configure global monitoring settings and notifications. + +### Email Notifications + +1. Toggle "Email Notifications" on +2. Select your email provider (Gmail, Outlook, Yahoo, or Custom) +3. Enter your email credentials +4. **For Gmail**: Use an App Password (see instructions in the UI) +5. Click "Send Test Email" to verify + +### Webhook Notifications + +1. Toggle "Webhook Notifications" on +2. Enter your webhook URL (Slack, Discord, etc.) +3. Click "Send Test Webhook" to verify + +### Other Settings + +- Timezone configuration +- Data retention period +- Alert thresholds +- SLA targets + +## Adding Resources + +1. Click "Add Resource" on the dashboard +2. Enter resource details: + - **Name**: Friendly name (e.g., "ZimaOS Home Server") + - **URL**: Full URL to monitor (e.g., "https://your-zima.example.com") + - **Check Interval**: How often to check (in milliseconds) + - **Timeout**: Maximum time to wait for response + - **Email To**: Email address for alerts (resource-specific) + - **HTTP Keyword**: Optional keyword to search for in response + - **SLA Target**: Target uptime percentage for this resource + +## SLA Report + +View Service Level Agreement compliance for all resources over configurable time periods.