Arcane-Status/README.md

Arcane Status

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

---

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

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

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

cp backend/.env.example backend/.env

Edit backend/.env and change the JWT secret to a strong random value:

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

npm run dev

Production (builds frontend, serves everything from the backend):

# 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

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

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

lsof -i :5000
lsof -i :3000
kill -9 <PID>

Database issues

Delete the database to reset (this loses all data):

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:

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.