GoZen Host Status Page

A production-ready status page built with Astro, Tailwind CSS, and React. Integrates with Uptime Kuma for real-time monitoring data.

Features

• 🟢 Real-time Status — Live polling from Uptime Kuma API
• 📊 90-Day Uptime Bars — Historical data visualization per service
• 🛠️ Maintenance Windows — Schedule and display planned maintenance
• 📧 Email Subscriptions — MailWizz integration for status updates
• 🌙 Dark/Light Mode — System preference with manual toggle
• 🔒 Security Hardened — XSS protection, input validation, DoS limits
• 🚀 CI/CD Ready — Webhook-based auto-deployment

Quick Start

# Clone and install
git clone https://git.gozen.host/gozenhost/status.gozen.host.git
cd status.gozen.host
npm install

# Configure
cp .env.example .env
# Edit .env with your Kuma API URL

# Run locally
npm run dev
# → http://localhost:4321

AI agent skills (new machine)

Agent Skills (impeccable, the Vercel web-design-guidelines/React set, etc.) are vendored in .agents/skills/ and symlinked into .claude/skills/, tracked in skills-lock.json. A fresh git clone already includes them — no extra step.

• To restore/repair them from the lockfile: npx skills experimental_install
• To update to latest: npx skills update

The Superpowers plugin is enabled per-project in .claude/settings.json (enabledPlugins), so opening the repo in Claude Code picks it up from the default Anthropic marketplace. New skills/plugins load at Claude Code startup — restart after cloning.

Configuration

Required: Uptime Kuma

KUMA_API_URL=https://status.gozen.host/api/status-page/your-slug

Optional: Email Subscriptions

MAILWIZ_API_URL=https://newsletter.example.com/api/
MAILWIZ_API_KEY=your-api-key
MAILWIZ_LIST_UID=your-list-uid

Optional: Data Retention

# Number of days to display in uptime bars (default: 90)
RETENTION_DAYS=90

See INSTALLATION.md for full setup guide.

Historical Data Collection

Uptime Kuma only returns ~50 recent heartbeats. To display accurate 90-day uptime bars, run the collector periodically:

# Manual run
node scripts/collect-heartbeats.js

# Cron (every 10 minutes)
*/10 * * * * cd /path/to/project && node scripts/collect-heartbeats.js

Storage Requirements

Period	Per Monitor	9 Monitors
1 day	~145 KB	~1.3 MB
30 days	~4.3 MB	~39 MB
90 days	~13 MB	~117 MB

Data is stored in data/history/*.json and auto-pruned after 90 days.

Recovering months the archive missed

The monthly archive (data/monthly-uptime/*.json, written by scripts/archive-monthly-uptime.js on the 1st of each month) records a month as null when the heartbeat history had nothing for it, typically because the collector cron was down. Two honest ways to fill those:

• From our own history (last RETENTION_DAYS): just run node scripts/archive-monthly-uptime.js again. Null months are recomputed whenever the history now covers them; measured months are never touched.
• From Uptime Kuma's database (much older): copy kuma.db and run python3 scripts/import-kuma-monthly.py kuma-copy.db (dry run) then --apply. Reads stat_daily (Kuma 2.x) or heartbeat (any version), fills only missing/null months, backs up first.

Values are never invented for months no source measured.

Monitor Configuration

Uptime Kuma monitors are split into Public (shown on status page) and Internal (health checks only).

Monitoring Strategy

Layer	Monitor Type	Purpose	Response Time
Public	TCP Port	Clean metrics for status page	10-50ms
Internal	HTTP Keyword	Deep health verification	500-2000ms

---

Public Monitors (Status Page)

Use TCP Port or lightweight HTTP for clean, fast metrics:

DNS Infrastructure

Name	Type	Target	Port
DNS Europe 1	TCP Port	ns1.gozenhost.com	53
DNS Europe 2	TCP Port	ns3.gozenhost.com	53
DNS Americas 1	TCP Port	ns2.gozenhost.com	53
DNS Americas 2	TCP Port	zen.gozenhost.com	53

Shared Hosting (cPanel/WHM)

Name	Type	Target	Port
Shared Hosting - US	TCP Port	us-server.example.com	2087
Shared Hosting - EU	TCP Port	eu-server.example.com	2087

Cloud Hosting (Enhance)

Name	Type	Target
Enhance Portal	HTTP Keyword	https://enhance.example.com/api/status → Keyword: ready
Cloud Node - US	TCP Port	us-node.example.com:443
Cloud Node - EU	TCP Port	eu-node.example.com:443

---

Internal Monitors (NOT on Status Page)

Use HTTP Keyword for deep health checks - catches issues TCP might miss:

cPanel/WHM Health

Name	Type	URL	Keyword
US Server - WHM Health	HTTP Keyword	https://us-server:2087/	WHM
US Server - cPanel	HTTP Keyword	https://us-server:2083/	cPanel
EU Server - WHM Health	HTTP Keyword	https://eu-server:2087/	WHM

Enhance Node Health

Name	Type	URL	Keyword
EU Node 1 - Agent	HTTP Keyword	https://eu-node1/api/status	ready
US Node 1 - Agent	HTTP Keyword	https://us-node1/api/status	ready

---

Recommended Status Page Groups

🌐 DNS Infrastructure          (4 services)
🖥️ Shared Hosting              (2 services)
☁️ Cloud Hosting               (3 services)
📊 Network Intelligence Tools  (4 services)
📧 Email Services              (3 services)
<0A> Billing & Account           (1 service)
🏗️ Infrastructure              (3+ services)

Default Monitor Settings

Setting	Value
Heartbeat Interval	60 seconds
Retries	3
Retry Interval	20 seconds
Timeout	48 seconds

Project Structure

├── src/
│   ├── components/     # Astro/React components
│   ├── lib/
│   │   └── kuma.ts     # Uptime Kuma API integration
│   └── pages/
│       └── api/        # Server endpoints
├── scripts/
│   ├── collect-heartbeats.js  # Historical data collector
│   ├── deploy.sh              # Deployment script
│   └── webhook-server.js      # CI/CD webhook listener
├── data/
│   └── history/        # Stored heartbeat data (gitignored)
└── INSTALLATION.md     # Full deployment guide

Deployment

Quick Deploy (Interactive Script)

# Run the deployment script
./scripts/deploy.sh

# Or specify platform directly:
./scripts/deploy.sh enhance   # Enhance Control Panel
./scripts/deploy.sh vps       # VPS with PM2
./scripts/deploy.sh systemd   # VPS with systemd
./scripts/deploy.sh docker    # Docker container
./scripts/deploy.sh zip       # Create package only

Supported Platforms

Platform	Command	Use Case
Enhance Panel	./scripts/deploy.sh enhance	Recommended for GoZen infrastructure
VPS (PM2)	./scripts/deploy.sh vps	Standard VPS with process manager
VPS (Systemd)	./scripts/deploy.sh systemd	VPS with system service
Docker	./scripts/deploy.sh docker	Container deployment
Package Only	./scripts/deploy.sh zip	Manual deployment

Enhance Panel Deployment

1. Build the package:

   ./scripts/deploy.sh enhance
   

2. Upload deploy-enhance-*.tar.gz to Enhance Panel

3. In Enhance terminal:

   tar -xzf deploy-enhance-*.tar.gz
   source ~/.nvm/nvm.sh && npm install --omit=dev
   

4. Configure .env with your settings

5. Set Working Directory: public_html

6. Set Startup Command: bash start.sh

7. Add Cron (for 90-day history): bash public_html/scripts/cron-collect.sh >/dev/null 2>&1

Reverse Proxy (Nginx)

server {
    listen 80;
    server_name status.gozen.host;

    location / {
        proxy_pass http://127.0.0.1:4321;
        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_cache_bypass $http_upgrade;
    }
}

SSL with Certbot

sudo certbot --nginx -d status.gozen.host

Maintenance Management

All maintenance is managed through Uptime Kuma dashboard — no code changes needed!

Scheduling Maintenance

1. Go to Uptime Kuma → Maintenance
2. Click + New Maintenance
3. Fill in:
   • Title: "System Upgrade"
   • Description: Details about the maintenance
   • Start/End Time: Schedule window
   • Affected Monitors: Select relevant services
   • Status Page: Link to "GOZEN Status"
4. Click "Start Maintenance" to activate (banner appears immediately)
5. Click "End Maintenance" when complete

Real-time Updates

• Banner: Appears at top when maintenance is active
• Card: Shows in "Scheduled Maintenance" section
• No redeploy needed — data comes from Uptime Kuma API

Environment Variables

Variable	Required	Description
KUMA_API_URL	✅	Uptime Kuma status page API URL
KUMA_API_KEY	❌	API key for read-only access
MAILWIZ_API_URL	❌	MailWizz API endpoint
MAILWIZ_API_KEY	❌	MailWizz API key
MAILWIZ_LIST_UID	❌	MailWizz subscriber list ID
SHOW_STABILITY_ENGINE	❌	Show response times (sparklines, ms tiles, chart, tooltip ping, /api/heartbeat ping). Default: hidden
RETENTION_DAYS	❌	Days to keep history (default: 90)
SLA_TARGET	❌	Contractual uptime % (e.g. 99.9) shown next to delivered uptime. Empty = delivered only
WEBHOOK_SECRET	❌	CI/CD webhook secret
WEBHOOK_PORT	❌	CI/CD webhook port (default: 9000)

Documentation

• INSTALLATION.md — Full deployment guide
• CHANGELOG.md — Version history

Tech Stack

• Framework: Astro 5.x (SSR with @astrojs/node)
• Styling: Tailwind CSS 3.x
• Components: React 19
• Monitoring: Uptime Kuma API
• Subscriptions: MailWizz API

License

MIT © GoZen Host