From e011afbff197c36910fc1d2e5629211c12a724f7 Mon Sep 17 00:00:00 2001 From: Rina Date: Thu, 16 Apr 2026 21:54:24 +0000 Subject: [PATCH] Update Readme Signed-off-by: Rina --- README.md | 231 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 229 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 73061b0..bc9299f 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,230 @@ -# Arcane-Status +

+ Arcane Status +

-Coming Soon \ No newline at end of file +

+ A self-hosted, real-time status page for monitoring your services, APIs, and infrastructure. +

+ +

+ + MIT License + Node.js 24 LTS + SQLite +

+ +--- + +# Arcane Status + +A **free and open source status page** you can self-host to monitor uptime, track incidents, and show your users a clean, real-time view of your services. No external database required, everything runs on SQLite. + +## Features + +**Real-time monitoring** — monitor HTTP/HTTPS endpoints, TCP ports, and ICMP ping with customisable check intervals from 10 seconds to 1 hour. + +**Live status updates** — WebSocket-powered real-time updates pushed to the public status page and admin dashboard as checks complete. + +**Admin dashboard** — add, edit and remove endpoints, manage incidents, configure site settings, manage users, and generate API keys from a single panel. + +**Public status page** — a clean, responsive page showing current status, response times, uptime stats, heatmaps, active incidents, and overall system health. + +**Incident management** — create, update, and resolve incidents with severity levels, link them to affected endpoints, and write post-mortems. + +**Scheduled maintenance** — schedule maintenance windows for endpoints to pause monitoring and display notice to visitors. + +**Uptime tracking** — automatic uptime percentage calculation with SLA tracking over configurable time periods, plus jitter and packet loss metrics for ping checks. + +**Role-based access** — admin and viewer roles with enforced permissions on all protected routes. + +**Email notifications** — SMTP-based notifications with per-user preferences. Subscribe to all endpoints or specific categories. Get notified on downtime, recovery, degradation, or incidents. + +**API access** — generate API keys for programmatic access to your status data. Rate-limited public API with status.json, summary, components, and incidents endpoints. + +**Custom branding** — rename your status page, customize the public URL, and configure SMTP for outgoing notifications. + +**Zero external dependencies** — SQLite database, no Redis or Postgres required. Just Node.js. + +> [!NOTE] +> See it in action here: [https://status.arcaneneko.com](https://status.arcaneneko.com) + +> [!NOTE] +> This project is actively developed. Slack/Discord notifications, detailed analytics, and more are planned for future releases. + +## Requirements + +- **Node.js 24 LTS** or newer +- A Linux, macOS, or Windows machine + +## Quick Start + +### 1. Clone and install + +```bash +git clone https://git.arcaneneko.com/ArcaneNeko/Arcane-Status +cd arcane-status + +# Install all dependencies (root, backend, and frontend) +npm run install-all +``` + +### 2. Configure + +```bash +cp backend/.env.example backend/.env +``` + +Edit `backend/.env` and **change the JWT secret** to a strong random value: + +```env +PORT=5000 +NODE_ENV=production +JWT_SECRET=replace_with_a_strong_random_string +DATABASE_PATH=../data/status.db +FRONTEND_URL=https://status.example.com +``` + +> [!IMPORTANT] +> Never deploy with the default JWT secret. Generate one with `openssl rand -hex 64` or similar. + +### 3. Run + +**Development** (runs React dev server + backend with hot reload): + +```bash +npm run dev +``` + +**Production** (builds frontend, serves everything from the backend): + +```bash +# Build the frontend +npm run build + +# Start the server +npm start +``` + +Everything runs on a single port in production: + +| | URL | +|---|---| +| **Status page** | http://localhost:5000 | +| **Admin panel** | http://localhost:5000/admin | +| **API** | http://localhost:5000/api | + +On first launch you'll be guided through a setup wizard to create your admin account and configure site settings. + +## Public API + +Arcane Status exposes a free, rate-limited (60 req/min) public API for integration: + +| Endpoint | Description | +|----------|-------------| +| `/api/v1/status.json` | Full status dump (primary integration) | +| `/api/v1/summary` | Lightweight summary (page name + overall status) | +| `/api/v1/components` | All monitored components | +| `/api/v1/incidents` | Current and past incidents | +| `/api/v1/scheduled-maintenances` | Upcoming scheduled maintenance | + +You can enrich responses by passing an API key via the `X-API-Key` header. + +## Production Deployment + +### Running with PM2 + +```bash +# Install PM2 globally +npm install -g pm2 + +# Build the frontend first +npm run build + +# Start the app +pm2 start "npm start" --name arcane-status + +# Auto-start on reboot +pm2 startup +pm2 save + +# View logs +pm2 logs arcane-status +``` + +### Using a Reverse Proxy (Nginx) + +Since everything runs on port 5000 in production, the Nginx config is straightforward: + +```nginx +server { + listen 80; + server_name status.example.com; + + location / { + proxy_pass http://localhost:5000; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection 'upgrade'; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_cache_bypass $http_upgrade; + proxy_buffering off; + } +} +``` + +> [!TIP] +> Use [Certbot](https://certbot.eff.org/) to add HTTPS with a free Let's Encrypt certificate. Update `FRONTEND_URL` in your `.env` to match your domain. + +## Troubleshooting + +
+Port already in use + +```bash +lsof -i :5000 +lsof -i :3000 +kill -9 +``` +
+ +
+Database issues + +Delete the database to reset (this loses all data): + +```bash +rm data/status.db +npm start +``` + +The database will be recreated automatically on startup. +
+ +
+WebSocket not connecting + +Make sure `FRONTEND_URL` in `backend/.env` matches your actual frontend URL. If using a reverse proxy, ensure the `/socket.io` path is proxied correctly. +
+ +
+Ping checks not working + +Ping checks require elevated privileges. On Linux, you may need to set the correct capability: + +```bash +sudo setcap cap_net_raw+ep $(which node) +``` + +Or run the backend as root (not recommended for production). +
+ +## License + +MIT + +--- + +Made with care for anyone who needs a simple, self-hosted status page. \ No newline at end of file