231
README.md
231
README.md
@@ -1,3 +1,230 @@
|
|||||||
# Arcane-Status
|
<p align="center">
|
||||||
|
<strong>Arcane Status</strong>
|
||||||
|
</p>
|
||||||
|
|
||||||
Coming Soon
|
<p align="center">
|
||||||
|
A self-hosted, real-time status page for monitoring your services, APIs, and infrastructure.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<a href="./LICENSE">
|
||||||
|
<img src="https://img.shields.io/badge/License-MIT-blue" alt="MIT License" /></a>
|
||||||
|
<img src="https://img.shields.io/badge/Node.js-24%20LTS-brightgreen" alt="Node.js 24 LTS" />
|
||||||
|
<img src="https://img.shields.io/badge/Database-SQLite-lightgrey" alt="SQLite" />
|
||||||
|
</p>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# 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
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><strong>Port already in use</strong></summary>
|
||||||
|
|
||||||
|
```bash
|
||||||
|
lsof -i :5000
|
||||||
|
lsof -i :3000
|
||||||
|
kill -9 <PID>
|
||||||
|
```
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><strong>Database issues</strong></summary>
|
||||||
|
|
||||||
|
Delete the database to reset (this loses all data):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
rm data/status.db
|
||||||
|
npm start
|
||||||
|
```
|
||||||
|
|
||||||
|
The database will be recreated automatically on startup.
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><strong>WebSocket not connecting</strong></summary>
|
||||||
|
|
||||||
|
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.
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><strong>Ping checks not working</strong></summary>
|
||||||
|
|
||||||
|
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).
|
||||||
|
</details>
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Made with care for anyone who needs a simple, self-hosted status page.
|
||||||
Reference in New Issue
Block a user