Yet Another Status Page

A modern, self-hosted status page built with Payload CMS and Next.js.

Features

• 🚨 Incident Management - Track and communicate service disruptions
• 🔧 Scheduled Maintenance - Plan and notify users about upcoming maintenance
• 📧 Email & SMS Notifications - Automatic subscriber notifications via SMTP and Twilio
• 📊 Service Groups - Organize services into logical groups
• 🎨 Beautiful UI - Modern, responsive status page with dark mode support
• 🔒 Self-Hosted - Full control over your data and infrastructure
• 🐳 Docker Ready - Easy deployment with Docker and Docker Compose

Quick Start

# Clone the repository
git clone https://github.com/Hostzero-GmbH/yet-another-status-page.git
cd yet-another-status-page

# Start with Docker Compose
docker compose up -d

Visit http://localhost:3000 to see your status page, and http://localhost:3000/admin to access the admin panel.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                 Yet Another Status Page                     │
├─────────────────────────────────────────────────────────────┤
│  Frontend (Next.js)          │  Admin Panel (Payload CMS)   │
│  - Status Page               │  - Manage Services           │
│  - Incident History          │  - Create Incidents          │
│  - Subscribe Form            │  - Schedule Maintenances     │
│                              │  - Send Notifications        │
├─────────────────────────────────────────────────────────────┤
│                     PostgreSQL Database                      │
└─────────────────────────────────────────────────────────────┘

Documentation

• Installation Guide - Get started with Yet Another Status Page
• Docker Compose Setup - Deploy with Docker
• Admin Guide - Learn how to manage your status page
• Notification Workflow - Understand the notification system

Installation

Yet Another Status Page can be deployed in several ways. Choose the method that best fits your infrastructure.

Prerequisites

• Docker and Docker Compose (recommended)
• OR Node.js 20+ and PostgreSQL 15+

Deployment Options

Option 1: Vercel (One-Click)

Deploy instantly to Vercel with a managed PostgreSQL database:

This will:

1. Create a new Vercel project
2. Provision a Vercel Postgres database
3. Prompt you to set PAYLOAD_SECRET (generate a random 32+ character string)

All configuration (site name, logos, services, notifications) is done through the admin panel — no code changes required.

Option 2: Docker Compose (Recommended for Self-Hosting)

The easiest way to self-host. See the Docker Compose guide for detailed instructions.

# Clone the repository
git clone https://github.com/Hostzero-GmbH/yet-another-status-page.git
cd yet-another-status-page

# Copy the example environment file
cp .env.example .env

# Edit the environment variables
nano .env

# Start the services
docker compose up -d

Option 3: Pre-built Docker Image

Pull the latest image from GitHub Container Registry:

docker pull ghcr.io/hostzero-gmbh/status-page:latest

Run with your own PostgreSQL:

docker run -d \
  --name status-page \
  -p 3000:3000 \
  -e DATABASE_URI=postgres://user:pass@host:5432/db \
  -e PAYLOAD_SECRET=your-secret-key \
  -e SERVER_URL=https://status.example.com \
  ghcr.io/hostzero-gmbh/status-page:latest

Option 4: Build from Source

# Clone the repository
git clone https://github.com/Hostzero-GmbH/yet-another-status-page.git
cd yet-another-status-page

# Install dependencies
npm install

# Build the application
npm run build

# Start the production server
npm start

First-Time Setup

1. Access the Admin Panel

   Navigate to http://your-server:3000/admin

2. Create Admin User

   On first access, you’ll be prompted to create an admin account.

3. Configure Settings

   Configure your status page in the admin panel:

   • Configuration → Site Settings: Site name, description, favicon, logos
   • Configuration → Email Settings: SMTP settings for email notifications
   • Configuration → SMS Settings: Twilio settings for SMS notifications

4. Add Services

   Create service groups and services that represent your infrastructure.

5. Go Live

   Your status page is now accessible at http://your-server:3000

Docker Compose Setup

This guide explains how to deploy Yet Another Status Page using Docker Compose.

Quick Start

1. Clone the Repository

git clone https://github.com/Hostzero-GmbH/yet-another-status-page.git
cd yet-another-status-page

2. Create Environment File

cp .env.example .env

Edit .env with your configuration:

# Database
DATABASE_URI=postgres://hostzero:your-secure-password@db:5432/hostzero_status
POSTGRES_PASSWORD=your-secure-password

# Security
PAYLOAD_SECRET=your-32-character-secret-key-here

# URLs
SERVER_URL=https://status.yourdomain.com

Note: Email (SMTP) and SMS (Twilio) settings are configured via the admin panel under Configuration → Email Settings and Configuration → SMS Settings, not through environment variables.

3. Start the Services

docker compose up -d

4. Access the Application

• Status Page: http://localhost:3000
• Admin Panel: http://localhost:3000/admin

Docker Compose File

Create a docker-compose.yml in your project root:

version: '3.8'

services:
  app:
    image: ghcr.io/hostzero-gmbh/status-page:latest
    # Or build from source:
    # build:
    #   context: ./cms
    #   dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URI=${DATABASE_URI}
      - PAYLOAD_SECRET=${PAYLOAD_SECRET}
      - SERVER_URL=${SERVER_URL}
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
    volumes:
      - uploads:/app/public/media

  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=hostzero
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=hostzero_status
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U hostzero -d hostzero_status"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  postgres_data:
  uploads:

Production Deployment

With Traefik (Recommended)

version: '3.8'

services:
  app:
    image: ghcr.io/hostzero-gmbh/status-page:latest
    environment:
      - DATABASE_URI=${DATABASE_URI}
      - PAYLOAD_SECRET=${PAYLOAD_SECRET}
      - SERVER_URL=https://status.yourdomain.com
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
    volumes:
      - uploads:/app/public/media
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.status.rule=Host(`status.yourdomain.com`)"
      - "traefik.http.routers.status.entrypoints=websecure"
      - "traefik.http.routers.status.tls.certresolver=letsencrypt"
      - "traefik.http.services.status.loadbalancer.server.port=3000"
    networks:
      - traefik
      - internal

  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=hostzero
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=hostzero_status
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U hostzero -d hostzero_status"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - internal

volumes:
  postgres_data:
  uploads:

networks:
  traefik:
    external: true
  internal:

With nginx

version: '3.8'

services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - app
    restart: unless-stopped

  app:
    image: ghcr.io/hostzero-gmbh/status-page:latest
    environment:
      - DATABASE_URI=${DATABASE_URI}
      - PAYLOAD_SECRET=${PAYLOAD_SECRET}
      - SERVER_URL=https://status.yourdomain.com
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
    volumes:
      - uploads:/app/public/media

  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=hostzero
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=hostzero_status
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U hostzero -d hostzero_status"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  postgres_data:
  uploads:

Updating

To update to the latest version:

# Pull the latest image
docker compose pull

# Restart with the new image
docker compose up -d

Backup & Restore

Backup Database

docker compose exec db pg_dump -U hostzero hostzero_status > backup.sql

Restore Database

cat backup.sql | docker compose exec -T db psql -U hostzero hostzero_status

Backup Uploads

docker compose cp app:/app/public/media ./media-backup

Configuration

Yet Another Status Page is configured through environment variables and the admin panel.

Environment Variables

Required

Note: On Vercel, both POSTGRES_URL and SERVER_URL are automatically detected:

• POSTGRES_URL is set when you add a Vercel Postgres database
• SERVER_URL falls back to VERCEL_PROJECT_PRODUCTION_URL or VERCEL_URL if not explicitly set

The app supports both DATABASE_URI and POSTGRES_URL for database connections.

Optional

SSO/OIDC Authentication (Optional)

Enable Single Sign-On with any OIDC-compliant identity provider (Keycloak, Okta, Auth0, Azure AD, Google).

Provider-Specific URLs

Keycloak:

OIDC_AUTH_URL=https://keycloak.example.com/realms/{realm}/protocol/openid-connect/auth
OIDC_TOKEN_URL=https://keycloak.example.com/realms/{realm}/protocol/openid-connect/token
OIDC_USERINFO_URL=https://keycloak.example.com/realms/{realm}/protocol/openid-connect/userinfo

Okta:

OIDC_AUTH_URL=https://{domain}.okta.com/oauth2/default/v1/authorize
OIDC_TOKEN_URL=https://{domain}.okta.com/oauth2/default/v1/token
OIDC_USERINFO_URL=https://{domain}.okta.com/oauth2/default/v1/userinfo

Auth0:

OIDC_AUTH_URL=https://{tenant}.auth0.com/authorize
OIDC_TOKEN_URL=https://{tenant}.auth0.com/oauth/token
OIDC_USERINFO_URL=https://{tenant}.auth0.com/userinfo

Azure AD:

OIDC_AUTH_URL=https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
OIDC_TOKEN_URL=https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
OIDC_USERINFO_URL=https://graph.microsoft.com/oidc/userinfo

Google:

OIDC_AUTH_URL=https://accounts.google.com/o/oauth2/v2/auth
OIDC_TOKEN_URL=https://oauth2.googleapis.com/token
OIDC_USERINFO_URL=https://openidconnect.googleapis.com/v1/userinfo

Callback URL

When configuring your identity provider, set the callback/redirect URL to:

https://your-status-page.com/api/users/oauth/callback

Group-Based Access Control

To restrict access to specific groups from your identity provider:

1. Configure your IdP to include group claims in the userinfo response
2. Set OIDC_ALLOWED_GROUPS to a comma-separated list of allowed groups
3. If your IdP uses a different claim name, set OIDC_GROUP_CLAIM

Example Keycloak Setup:

1. Create a client scope named “groups” with a Group Membership mapper:
   • Token Claim Name: groups
   • Add to userinfo: On
2. Add the scope to your client
3. Configure the status page:

OIDC_SCOPES=openid profile email groups
OIDC_ALLOWED_GROUPS=status-page-admins,status-page-editors

SSO-Only Mode

To disable password login and require SSO for all users:

OIDC_DISABLE_LOCAL_LOGIN=true

Warning: Ensure SSO is working correctly before enabling this option, or you may lock yourself out!

Admin Panel Settings

The admin panel has three configuration sections under Configuration:

Site Settings

Access Configuration → Site Settings to configure:

• Site Name: Displayed in the header and emails
• Site Description: Meta description for SEO
• Favicon: Custom favicon for your status page
• Logos: Light and dark theme logos
• SEO: Meta titles and descriptions
• Status Override: Maintenance mode and custom messages

Email Settings

Access Configuration → Email Settings to configure email notifications:

SMS Settings

Access Configuration → SMS Settings to configure SMS notifications:

SMS Templates

You can customize the SMS message templates with these placeholders:

Available templates:

• New Incident Template - For initial incident notifications
• Incident Update Template - For incident status updates
• New Maintenance Template - For scheduled maintenance announcements
• Maintenance Update Template - For maintenance status updates

You can also configure Title Max Length and Message Max Length to control truncation.

Testing Notifications

After configuring SMTP or Twilio:

1. Create a test subscriber in Notifications → Subscribers
2. Create a test incident in Status → Incidents
3. Check the Notifications collection for the auto-generated draft
4. Click Send Notification Now to test

Security Recommendations

1. Use strong secrets: Generate a random 32+ character string for PAYLOAD_SECRET
2. Use HTTPS: Always deploy behind HTTPS in production
3. Secure database: Use strong passwords and restrict database access
4. Regular backups: Schedule regular database backups

Admin Overview

The Yet Another Status Page admin panel is powered by Payload CMS and provides a comprehensive interface for managing your status page.

Dashboard

The dashboard shows at-a-glance metrics:

• Active Incidents - Current unresolved incidents
• Upcoming Maintenances - Scheduled or in-progress maintenance windows
• Draft Notifications - Notifications waiting to be sent
• Scheduled Notifications - Notifications being processed
• Email Subscribers - Active email subscribers
• SMS Subscribers - Active SMS subscribers

Navigation

The admin panel is organized into sections:

Status

• Service Groups - Logical groupings of services
• Services - Individual services to monitor
• Incidents - Service disruptions and issues
• Maintenances - Scheduled maintenance windows

Notifications

• Notifications - Manage and send notifications
• Subscribers - Manage subscriber list

Admin

• Users - Admin user accounts
• Media - Uploaded files and images

Configuration

• Site Settings - Site name, branding, SEO, status overrides
• Email Settings - SMTP configuration and email subscriptions
• SMS Settings - Twilio configuration, SMS subscriptions, and message templates

Workflow Overview

┌─────────────────────────────────────────────────────────────┐
│  1. Create Services                                         │
│     Define your infrastructure components                    │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  2. Incident Occurs                                         │
│     Create incident → Notification draft auto-created       │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  3. Review & Send                                           │
│     Go to Notifications → Review → Send                     │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  4. Add Updates                                             │
│     Post updates → New notification drafts auto-created     │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  5. Resolve                                                 │
│     Mark resolved → Final notification                      │
└─────────────────────────────────────────────────────────────┘

Quick Actions

Creating an Incident

1. Go to Status → Incidents
2. Click Create New
3. Fill in the title, affected services, status, and impact
4. Click Save
5. A notification draft is automatically created

Scheduling Maintenance

1. Go to Status → Maintenances
2. Click Create New
3. Set the title, affected services, and schedule
4. Click Save
5. A notification draft is automatically created

Sending Notifications

1. Go to Notifications → Notifications
2. Find the draft notification
3. Review and edit the content if needed
4. Click Send Notification Now

Managing Services

Services represent the components of your infrastructure that you want to display on the status page.

Service Groups

Service groups organize related services together.

Creating a Service Group

1. Go to Status → Service Groups
2. Click Create New
3. Enter a name (e.g., “Core Infrastructure”, “API Services”)
4. Optionally add a description
5. Click Save

Ordering Groups

Drag and drop service groups to reorder them on the status page.

Services

Services are individual components within a group.

Creating a Service

1. Go to Status → Services
2. Click Create New
3. Fill in:
   • Name - Display name (e.g., “API Gateway”)
   • Description - Brief description
   • Service Group - Which group it belongs to
   • Status - Current operational status
4. Click Save

Service Statuses

Automatic Status Updates

Service status is automatically updated when:

• An incident is created affecting the service
• An incident is resolved
• A maintenance window starts or ends

You can also manually update the status at any time.

Best Practices

Naming

• Use clear, user-facing names
• Avoid internal jargon
• Be consistent with naming conventions

Grouping

• Group by function (e.g., “Core”, “APIs”, “Integrations”)
• Keep groups manageable (5-10 services each)
• Consider your users’ perspective

Granularity

• Not too broad (users need to know what’s affected)
• Not too narrow (too many services is overwhelming)
• Aim for 10-30 total services for most deployments

Managing Incidents

Incidents represent unplanned service disruptions or issues affecting your infrastructure.

Creating an Incident

1. Go to Status → Incidents
2. Click Create New
3. Fill in the incident details:
   • Title - Brief description (e.g., “API Gateway Latency Issues”)
   • Affected Services - Select impacted services
   • Status - Current investigation status
   • Impact - Severity level
4. Click Save

A notification draft is automatically created when you save.

Incident Statuses

Status Flow

Investigating → Identified → Monitoring → Resolved

You can skip statuses if appropriate (e.g., go directly to Resolved for quick fixes).

Impact Levels

Adding Updates

As the incident progresses, add updates to the timeline:

1. Open the incident
2. Scroll to Updates
3. Click Add Update
4. Fill in:
   • Status - Current status
   • Message - Update details
   • Created At - When this update occurred
5. Click Save

A new notification draft is automatically created for each update.

Resolving an Incident

1. Open the incident
2. Change Status to “Resolved”
3. The Resolved At timestamp is automatically set
4. Click Save
5. Review and send the final notification

Incident Permalinks

Each incident gets a unique short ID (e.g., abc123) that creates a permanent link:

https://status.example.com/i/abc123

This link is included in notifications and remains valid even if the title changes.

Best Practices

Titles

• Be specific but concise
• Include the affected component
• Avoid blame or technical jargon

Good: “Payment Processing Delays” Bad: “Database server crashed due to OOM killer”

Updates

• Post updates every 30-60 minutes during active incidents
• Be honest about what you know and don’t know
• Set expectations for next update

Resolution

• Confirm the issue is fully resolved before closing
• Include a brief summary of what happened
• Thank users for their patience

Example Timeline

┌─────────────────────────────────────────────────────────────┐
│ API Gateway Latency Issues                                  │
├─────────────────────────────────────────────────────────────┤
│ 🟡 Investigating - 10:00 AM                                 │
│    We are investigating reports of slow API responses.      │
├─────────────────────────────────────────────────────────────┤
│ 🟡 Identified - 10:30 AM                                    │
│    Root cause identified as a misconfigured load balancer.  │
│    Our team is implementing a fix.                          │
├─────────────────────────────────────────────────────────────┤
│ 🟢 Monitoring - 11:00 AM                                    │
│    Fix deployed. We are monitoring for stability.           │
├─────────────────────────────────────────────────────────────┤
│ 🟢 Resolved - 11:30 AM                                      │
│    This incident has been resolved. API response times      │
│    have returned to normal.                                 │
└─────────────────────────────────────────────────────────────┘

Managing Maintenances

Maintenances represent planned service interruptions or maintenance windows.

Creating a Maintenance

1. Go to Status → Maintenances
2. Click Create New
3. Fill in the maintenance details:
   • Title - Brief description (e.g., “Database Migration”)
   • Description - Detailed explanation (optional)
   • Affected Services - Select impacted services
   • Scheduled Start - When maintenance begins
   • Scheduled End - When maintenance ends (optional)
   • Duration - Human-readable duration (e.g., “~2 hours”)
4. Click Save

A notification draft is automatically created when you save.

Maintenance Statuses

Auto-Status Updates

Enable automatic status transitions:

• Auto-start on schedule - Automatically changes to “In Progress” when the scheduled start time is reached
• Auto-complete on schedule - Automatically changes to “Completed” when the scheduled end time is reached

These can be enabled/disabled per maintenance.

Adding Updates

During maintenance, add updates to keep users informed:

1. Open the maintenance
2. Scroll to Updates
3. Click Add Update
4. Fill in:
   • Status - Current status
   • Message - Progress update
   • Created At - When this update occurred
5. Click Save

A new notification draft is automatically created for each update.

Maintenance Permalinks

Each maintenance gets a unique short ID (e.g., xyz789) that creates a permanent link:

https://status.example.com/m/xyz789

Notification Content

Initial Notification (Email)

A maintenance window has been scheduled.

Scheduled Start: Sat, Jan 11 at 2:00 AM
Scheduled End: Sat, Jan 11 at 4:00 AM
Expected Duration: ~2 hours

We will notify you when the maintenance begins and completes.

View full details: https://status.example.com/m/xyz789

Initial Notification (SMS)

🔧 MAINTENANCE: Database Migration

📅 Sat, Jan 11 at 2:00 AM - Sat, Jan 11 at 4:00 AM

We will notify you when maintenance begins and completes.

Details: https://status.example.com/m/xyz789

Best Practices

Scheduling

• Schedule during low-traffic periods
• Give users at least 24-48 hours notice
• Avoid scheduling during holidays or major events

Communication

• Be clear about what will be affected
• Provide estimated duration
• Notify at key milestones (start, 50%, complete)

Timing

• Send initial notification 24-48 hours before
• Send reminder 1-2 hours before
• Send “started” notification when beginning
• Send “completed” notification when done

Example Timeline

┌─────────────────────────────────────────────────────────────┐
│ Database Migration                                          │
│ Scheduled: Jan 11, 2:00 AM - 4:00 AM EST                   │
├─────────────────────────────────────────────────────────────┤
│ 📅 Scheduled - Jan 9, 10:00 AM                              │
│    Scheduled maintenance for database migration.            │
├─────────────────────────────────────────────────────────────┤
│ 🔧 In Progress - Jan 11, 2:00 AM                           │
│    Maintenance has begun. Services may be unavailable.      │
├─────────────────────────────────────────────────────────────┤
│ 🔧 In Progress - Jan 11, 3:00 AM                           │
│    Migration 75% complete. On track for scheduled end.      │
├─────────────────────────────────────────────────────────────┤
│ ✅ Completed - Jan 11, 3:45 AM                              │
│    Maintenance completed successfully. All services         │
│    have been restored.                                      │
└─────────────────────────────────────────────────────────────┘

Notification Workflow

Yet Another Status Page includes a powerful notification system that automatically creates notification drafts and allows you to review before sending.

How It Works

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  Create/Update   │ ──▶ │  Draft Created   │ ──▶ │  Review & Send   │
│  Incident or     │     │  Automatically   │     │  from Admin      │
│  Maintenance     │     │                  │     │                  │
└──────────────────┘     └──────────────────┘     └──────────────────┘

Automatic Draft Creation

Notification drafts are automatically created when:

1. New Incident Created - A draft with incident details is created
2. Incident Updated - When you add an update to the timeline, a new draft is created
3. New Maintenance Scheduled - A draft with schedule details is created
4. Maintenance Updated - When you add an update, a new draft is created

Manual Review & Send

Notifications are never sent automatically. You must:

1. Go to Notifications → Notifications
2. Review the draft content
3. Edit if needed
4. Click Send Notification Now

This gives you full control over what gets sent to subscribers.

Notification Statuses

Notification Channels

Each notification can be sent via:

• Email - Sends to email subscribers only
• SMS - Sends to SMS subscribers only
• Both - Sends to all subscribers

Email Notifications

Content

Email notifications include:

• Subject line
• Formatted HTML body
• Call-to-action button linking to the status page
• Unsubscribe link (required for compliance)

Headers

Emails automatically include:

• List-Unsubscribe header for one-click unsubscribe
• List-Unsubscribe-Post header for RFC 8058 compliance

Configuration

Configure SMTP in Configuration → Email Settings:

• Enable Email Subscriptions toggle
• SMTP Host, Port, Security
• Authentication credentials
• From address and name

SMS Notifications

Content

SMS messages are generated from customizable templates and include:

• Site name prefix
• Emoji indicator (🚨 incident, 🔧 maintenance)
• Title and status
• Scheduled times (for maintenance)
• Link to status page

Configuration

Configure Twilio in Configuration → SMS Settings:

• Enable SMS Subscriptions toggle
• Account SID
• Auth Token
• From phone number OR Messaging Service SID

SMS Templates

You can customize SMS message templates in Configuration → SMS Settings under the “SMS Templates” section. Available placeholders:

• {{siteName}} - Your site name
• {{title}} - Incident/maintenance title
• {{status}} - Current status
• {{message}} - Update message
• {{schedule}} - Maintenance schedule
• {{url}} - Link to the page

Configure Title Max Length and Message Max Length to control how content is truncated to fit SMS limits.

Recipient Count

The notification form shows the estimated recipient count based on:

• Selected channel (Email/SMS/Both)
• Active subscribers matching that channel

After sending, it shows the actual number of recipients.

Retrying Failed Notifications

If a notification fails:

1. The error message is displayed in the notification form
2. The Retry Send button allows you to attempt again
3. Fix any configuration issues before retrying

Common failure reasons:

• SMTP not configured
• Twilio not configured
• Invalid credentials
• Network issues

Best Practices

Writing Notifications

1. Be concise - Get to the point quickly
2. Include impact - What services are affected?
3. Set expectations - When will it be resolved?
4. Provide updates - Keep subscribers informed

Timing

1. Send promptly - Notify as soon as you’re aware
2. Update regularly - Post updates at least hourly during incidents
3. Confirm resolution - Always send a final “resolved” notification

Testing

1. Create a test subscriber (your email/phone)
2. Create a test incident
3. Send the notification to verify delivery
4. Delete test data when done

Subscribers

Managing Subscribers

Go to Notifications → Subscribers to:

• View all subscribers
• Add subscribers manually
• Deactivate subscribers
• See subscription type (email/SMS)

Subscription Types

• Email - Requires valid email address
• SMS - Requires phone number with country code

Active vs Inactive

• Active - Will receive notifications
• Inactive - Opted out or deactivated

Subscribers can unsubscribe via the link in emails, which sets them to inactive.

Automation & Jobs Queue

Notifications are sent via a background jobs queue:

• Prevents timeouts for large subscriber lists
• Automatic retries on failure (up to 3 attempts)
• Progress tracking in the notification status

The queue processes immediately in development and can be scaled with workers in production.

Managing Subscribers

Subscribers receive notifications about incidents and maintenance windows.

Subscription Types

Each subscriber has one type. Users who want both should create two subscriptions.

Adding Subscribers

Manual Addition

1. Go to Notifications → Subscribers
2. Click Create New
3. Fill in:
   • Type - Email or SMS
   • Email - Email address (for email type)
   • Phone - Phone number with country code (for SMS type)
   • Verified - Whether the subscription is verified
   • Active - Whether to send notifications
4. Click Save

Public Subscription

Users can subscribe via the public status page:

1. Click the “Subscribe” button on the status page
2. Enter their email or phone number
3. They appear in the Subscribers list

Subscriber Fields

Active vs Inactive

• Active - Subscriber will receive notifications
• Inactive - Subscriber will NOT receive notifications

Subscribers become inactive when:

• They click the unsubscribe link in an email
• An admin manually deactivates them

Unsubscribe Flow

Each email includes an unsubscribe link:

https://status.example.com/unsubscribe/{token}

When clicked:

1. User sees a confirmation message
2. Subscription is set to inactive
3. They no longer receive notifications

The unsubscribe link is unique per subscriber and doesn’t expire.

Phone Number Format

SMS phone numbers must include the country code:

• ✅ +14155551234 (US)
• ✅ +442071234567 (UK)
• ✅ +33123456789 (France)
• ❌ 415-555-1234 (missing country code)
• ❌ (415) 555-1234 (missing country code)

Verification

The Verified field indicates whether the email/phone has been confirmed.

For manually added subscribers, you can set this to true if you’ve verified the contact information.

Bulk Operations

To deactivate multiple subscribers:

1. Select subscribers in the list view
2. Use bulk actions to update

Privacy Considerations

• Store only necessary contact information
• Provide easy unsubscribe options
• Respect unsubscribe requests immediately
• Consider data retention policies

Local Development Setup

This guide explains how to set up Yet Another Status Page for local development.

Prerequisites

• Node.js 20+
• PostgreSQL 15+ (or Docker)
• npm or pnpm

Quick Start with Docker

The easiest way to develop locally is using the included Docker Compose configuration.

# Clone the repository
git clone https://github.com/Hostzero-GmbH/yet-another-status-page.git
cd yet-another-status-page

# Start the development environment
docker compose -f docker-compose.dev.yml up -d postgres  # Start only the database

# Install dependencies
npm install

# Run database migrations
npm run payload migrate

# Start the development server
npm run dev

Visit:

• Status page: http://localhost:3333
• Admin panel: http://localhost:3333/admin

Note: The dev compose file uses port 3333 to avoid conflicts with production on port 3000.

Manual Setup

1. Install PostgreSQL

# macOS with Homebrew
brew install postgresql@16
brew services start postgresql@16

# Create database
createdb hostzero_status

2. Clone and Install

git clone https://github.com/Hostzero-GmbH/yet-another-status-page.git
cd yet-another-status-page
npm install

3. Configure Environment

cp .env.example .env

Edit .env:

DATABASE_URI=postgres://localhost:5432/hostzero_status
PAYLOAD_SECRET=your-development-secret-key
SERVER_URL=http://localhost:3000

4. Run Migrations

npm run payload migrate

5. Start Development Server

npm run dev

Development Scripts

Project Structure

status-page/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── (frontend)/         # Public status pages
│   │   ├── (payload)/          # Admin panel
│   │   └── api/                # API routes
│   ├── collections/            # Payload CMS collections
│   ├── components/             # React components
│   │   ├── admin/              # Admin panel components
│   │   └── status/             # Status page components
│   ├── globals/                # Payload CMS globals
│   ├── lib/                    # Utility functions
│   └── tasks/                  # Background job handlers
├── public/                     # Static assets
├── payload.config.ts           # Payload CMS configuration
└── tailwind.config.ts          # Tailwind CSS configuration

Making Changes

Adding a Collection

1. Create a new file in src/collections/
2. Export the collection config
3. Import and add to payload.config.ts
4. Run npm run payload generate:types
5. Run migrations if needed

Adding a Custom Admin Component

1. Create component in src/components/admin/
2. Reference it in the collection config
3. Run npm run payload generate:importmap

Adding an API Endpoint

1. Create a route file in src/app/api/
2. Export GET, POST, etc. handlers

Testing

# Type checking
npm run typecheck

# Build test
npm run build

Debugging

Database Issues

# Connect to database
psql $DATABASE_URI

# Reset database
dropdb hostzero_status && createdb hostzero_status
npm run payload migrate

Clear Cache

rm -rf .next
npm run dev

Architecture

Yet Another Status Page is built with modern technologies for reliability and developer experience.

Tech Stack

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Clients                               │
│  (Browsers, API Consumers, Email Clients, SMS)              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Next.js Application                       │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │  Status Pages   │  │   Admin Panel   │  │  REST API   │ │
│  │  (Frontend)     │  │  (Payload CMS)  │  │  Endpoints  │ │
│  └─────────────────┘  └─────────────────┘  └─────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                      Payload CMS Core                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │ Collections │  │   Globals   │  │    Jobs Queue       │ │
│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      PostgreSQL                              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   External Services                          │
│  ┌─────────────────┐           ┌─────────────────┐         │
│  │   SMTP Server   │           │     Twilio      │         │
│  │   (Email)       │           │     (SMS)       │         │
│  └─────────────────┘           └─────────────────┘         │
└─────────────────────────────────────────────────────────────┘

Data Model

Collections

┌─────────────────┐     ┌─────────────────┐
│  ServiceGroups  │────▶│    Services     │
│  - name         │     │  - name         │
│  - description  │     │  - status       │
│  - order        │     │  - group        │
└─────────────────┘     └─────────────────┘
                              │
                    ┌─────────┴─────────┐
                    ▼                   ▼
           ┌─────────────────┐  ┌─────────────────┐
           │   Incidents     │  │  Maintenances   │
           │  - title        │  │  - title        │
           │  - status       │  │  - status       │
           │  - impact       │  │  - schedule     │
           │  - updates[]    │  │  - updates[]    │
           └─────────────────┘  └─────────────────┘
                    │                   │
                    └─────────┬─────────┘
                              ▼
                    ┌─────────────────┐
                    │  Notifications  │
                    │  - title        │
                    │  - channel      │
                    │  - status       │
                    │  - content      │
                    └─────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │   Subscribers   │
                    │  - type         │
                    │  - email/phone  │
                    │  - active       │
                    └─────────────────┘

Globals

• Settings - Site configuration, SMTP, Twilio credentials

Request Flow

Status Page Request

Browser → Next.js → Server Component → Payload API → PostgreSQL
                          ↓
                    Rendered HTML

Admin Panel Request

Browser → Next.js → Payload Admin → Payload API → PostgreSQL
                          ↓
                    React SPA

Notification Flow

Save Incident → afterChange Hook → Create Notification Draft
                                          ↓
                              Admin Reviews Draft
                                          ↓
                              Click "Send Now"
                                          ↓
                              API Queues Job
                                          ↓
                              Jobs Queue Processes
                                          ↓
                              SMTP/Twilio Sends
                                          ↓
                              Update Notification Status

Key Design Decisions

Why Payload CMS?

• Modern, TypeScript-first CMS
• Excellent admin UI out of the box
• Flexible data modeling
• Built-in authentication
• Jobs queue for background tasks

Why Next.js App Router?

• Server components for performance
• Streaming and suspense support
• Built-in API routes
• Excellent developer experience

Why PostgreSQL?

• Robust and reliable
• Excellent JSON support
• Widely supported
• Easy to backup and scale

Why Separate Notifications Collection?

• Audit trail of all notifications
• Review before sending
• Retry failed notifications
• Clear status tracking

Scaling Considerations

Horizontal Scaling

• Application is stateless
• Can run multiple instances behind load balancer
• Shared PostgreSQL database

Database

• Connection pooling (PgBouncer)
• Read replicas for high traffic
• Regular backups

Jobs Queue

• Can add dedicated worker processes
• Automatic retries on failure
• Scales with subscriber count

REST API

Yet Another Status Page provides a REST API for programmatic access to status data.

Base URL

https://your-status-page.com/api

Authentication

Most read endpoints are public. Admin endpoints require authentication via:

• Session cookie (from admin login)
• API key header: Authorization: Bearer <api-key>

Endpoints

Incidents

List Incidents

GET /api/incidents

Query parameters:

Get Incident

GET /api/incidents/:id

Maintenances

List Maintenances

GET /api/maintenances

Query parameters same as incidents.

Get Maintenance

GET /api/maintenances/:id

Services

List Services

GET /api/services

Get Service

GET /api/services/:id

Service Groups

List Service Groups

GET /api/service-groups

Get Service Group

GET /api/service-groups/:id

Subscribers

Subscribe

POST /api/subscribe
Content-Type: application/json

{
  "type": "email",
  "email": "user@example.com"
}

Response:

{
  "success": true,
  "message": "Subscription successful"
}

Unsubscribe

POST /api/unsubscribe
Content-Type: application/json

{
  "token": "unsubscribe-token"
}

Payload REST API

The full Payload REST API is available at /api. See the Payload documentation for complete details.

Common Patterns

Filtering

GET /api/incidents?where[status][equals]=investigating

Sorting

GET /api/incidents?sort=-createdAt

Pagination

GET /api/incidents?limit=10&page=2

Field Selection

GET /api/incidents?select[title]=true&select[status]=true

GraphQL

A GraphQL endpoint is available at:

POST /api/graphql

GraphQL Playground (development only):

GET /api/graphql-playground

Rate Limiting

Public endpoints are rate limited to prevent abuse:

• 100 requests per minute per IP for read endpoints
• 10 requests per minute per IP for subscribe endpoint

Error Responses

All errors follow this format:

{
  "errors": [
    {
      "message": "Error description"
    }
  ]
}

Common HTTP status codes: