skywatch/README.md

SkyWatch

A comprehensive monitoring system for tracking the uptime and performance of your ZimaOS server and other online resources.

Features

• 📊 Real-time Dashboard - Monitor all your resources at a glance
• 📈 Performance Graphs - Visualize response times and uptime statistics
• 🔔 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 Install on Ubuntu (One Command)

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:

npm run install-all

2. Create a .env file in the root directory (copy from .env.example):

cp .env.example .env

3. Configure your .env file:

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

Usage

Development Mode

Run both server and client in development mode:

npm run dev

• Server runs on http://localhost:3001
• Client runs on http://localhost:3000

Production Mode

Build and run in production:

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:

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

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

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:

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:

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:

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:

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

[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:

sudo systemctl enable resource-monitor
sudo systemctl start resource-monitor

Windows (NSSM - Non-Sucking Service Manager):

# 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):

# 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):

sudo ufw allow 3001/tcp

Windows:

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:

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

API Endpoints

• GET /api/resources - List all resources
• POST /api/resources - Create new resource
• GET /api/resources/:id - Get resource details
• PUT /api/resources/:id - Update resource
• DELETE /api/resources/:id - Delete resource
• GET /api/dashboard - Dashboard overview
• GET /api/incidents - Recent incidents

Project Structure

mon/
├── server/              # Backend Node.js/Express
│   ├── index.js        # Main server file
│   ├── database.js     # SQLite database setup
│   ├── monitorService.js
│   ├── notificationService.js
│   └── scheduler.js
├── client/             # React frontend
│   └── src/
│       ├── App.js      # Main React component
│       └── App.css     # Styles
├── data/               # SQLite database (auto-created)
├── .env                # Environment configuration
└── package.json

Configuration

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:

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

License

MIT