- JavaScript 46.5%
- Python 19.3%
- TypeScript 14.9%
- Astro 12.5%
- Shell 3.4%
- Other 3.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .agents/skills | ||
| .claude | ||
| .forgejo | ||
| .superpowers/brainstorm/3579716-1777153570/content | ||
| docs | ||
| public | ||
| scripts | ||
| src | ||
| tests | ||
| whmcs-hooks | ||
| .dockerignore | ||
| .editorconfig | ||
| .env.example | ||
| .gitignore | ||
| astro.config.mjs | ||
| CHANGELOG.md | ||
| DESIGN.md | ||
| docker-compose.yml | ||
| Dockerfile | ||
| INSTALLATION.md | ||
| map.svg | ||
| package-lock.json | ||
| package.json | ||
| postcss.config.mjs | ||
| push2git.sh | ||
| README.md | ||
| ROADMAP.md | ||
| skills-lock.json | ||
| tailwind.config.mjs | ||
| tsconfig.json | ||
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
- 📊 Uptime History Bars — Per-service history (
RETENTION_DAYS, default 120 days) plus a monthly uptime archive - 🛠️ 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 — Forgejo Actions: type-check gate, staged server build, atomic swap, health check
Quick Start
# Clone and install
git clone https://git.gozen.host/gozenhost/status.gozen.host.git
cd status.gozen.host
npm ci
# Configure
cp .env.example .env
# Edit .env with your Kuma API URL
# Run locally
npm run dev
# → http://localhost:4321
# Production: build, then run the built server
npm run build
node dist/server/entry.mjs
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 kept and shown in uptime bars (default: 120)
RETENTION_DAYS=120
See INSTALLATION.md for full setup guide.
Historical Data Collection
Uptime Kuma only returns ~50 recent heartbeats. To display accurate uptime bars, run the collector every 10 minutes and the monthly archiver on the 1st, from the crontab of the user that runs the app (not root):
*/10 * * * * /path/to/project/scripts/cron-collect.sh
CRON_TZ=UTC
5 0 1 * * /path/to/project/scripts/cron-collect-monthly.sh
The wrappers load nvm and .env, use flock to avoid overlapping runs and log
to logs/. Run either one by hand to test. Details: INSTALLATION.md §3.
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 |
| 120 days | ~17 MB | ~156 MB |
Data is stored in data/history/*.json and auto-pruned after RETENTION_DAYS (default 120).
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 runscripts/cron-collect-monthly.shagain. Null months are recomputed whenever the history now covers them; measured months are never touched. - From Uptime Kuma's database (much older): copy
kuma.dband runpython3 scripts/import-kuma-monthly.py kuma-copy.db(dry run) then--apply. Readsstat_daily(Kuma 2.x) orheartbeat(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
│ ├── archive-monthly-uptime.js # Monthly uptime archiver
│ ├── cron-collect*.sh # Cron wrappers for the two above
│ └── deploy.sh # Packaging/deploy for non-production installs
├── .forgejo/workflows/ci-cd.yml # Production CI/CD
├── data/ # Runtime data, gitignored (history/, monthly-uptime/)
└── INSTALLATION.md # Full deployment guide
Deployment
Production (status.gozenhost.com, Enhance) is deployed automatically by
Forgejo Actions on every push to main — see .forgejo/SETUP.md.
The server is not a git checkout; don't git pull or build there by hand.
In every setup the app is the built server, node dist/server/entry.mjs.
Quick Deploy (Interactive Script, other installs)
# 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 (docker compose up -d --build)
./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 | docker compose up -d --build |
App + collector + archiver containers, see docs/DEPLOY_DOCKER.md |
| Package Only | ./scripts/deploy.sh zip |
Manual deployment |
Enhance Panel Deployment
-
Build the package:
./scripts/deploy.sh enhance -
Upload
deploy-enhance-*.tar.gzto Enhance Panel -
In Enhance terminal:
tar -xzf deploy-enhance-*.tar.gz source ~/.nvm/nvm.sh && npm ci --omit=dev -
Configure
.envwith your settings -
Set Working Directory:
public_html -
Set Startup Command:
bash start.sh -
Add the cron jobs as the site user (they log to
public_html/logs/):- every 10 minutes:
bash $HOME/public_html/scripts/cron-collect.sh - 1st of month 00:05 UTC:
bash $HOME/public_html/scripts/cron-collect-monthly.sh
- every 10 minutes:
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
- Go to Uptime Kuma → Maintenance
- Click + New Maintenance
- 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"
- Click "Start Maintenance" to activate (banner appears immediately)
- 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 of history kept and shown (default: 120) |
SLA_TARGET |
❌ | Contractual uptime % (e.g. 99.9) shown next to delivered uptime. Empty = delivered only |
WEBHOOK_SECRET |
❌ | X-Webhook-Secret value required by POST /api/alert-webhook |
ADMIN_TOKEN |
❌ | Protects the admin maintenance API |
Full list (incl. DATA_DIR, MAILWIZ_TIMEZONE, SUBSCRIBE_DOUBLE_OPT_IN,
TRUSTED_PROXY_HOPS): .env.example and INSTALLATION.md.
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