Open Source ❤️, Simple and Self-Hosted Monitoring Platform

Features • Quick Start • Contributing

Overview

Status Page is a lightweight, self-hosted monitoring platform designed to provide real-time visibility into your infrastructure's health.

Admin panel screenshots

Key Highlights

• User-Friendly Interface - Easy setup and configuration
• Real-time Monitoring - Instant updates on service availability
• Easy Deployment - Docker/Kubernetes support with comprehensive configuration options
• Flexible Monitoring - HTTP endpoint checks with customizable validation rules

Features

• HTTP Endpoint Monitoring - Track service availability with configurable health checks
• Additional Protocols - TCP, DNS, ICMP and more monitoring
• Custom Error Mapping - Define specific error conditions and responses
• Status Validation - Verify response codes, content patterns, and latency thresholds
• Service Grouping - Organize monitors into logical groups for better visibility
• Notifications - Notify when incidents occur
• Theme Presets - Ready-to-use color schemes (default, modern, dark)

Technologies

• FastAPI (API/SSR)
• SQLAlchemy/Alembic
• Dependency Injector
• Jinja2 + AlpineJS
• TailwindCSS (PostCSS)

Quick Start

Prerequisites

• Python 3.12+
• Node.js 20+ (npm 11+)
• Docker and Docker Compose (optional)
• Make (for development commands)

Installation

Warning

Review .env.example and update all credentials before deployment

Option 1: Docker Compose (Pre-built)

mkdir -p status-page && cd status-page
wget https://raw.githubusercontent.com/goldpulpy/status-page/main/docker-compose.yaml
wget https://raw.githubusercontent.com/goldpulpy/status-page/main/.env.example
cp .env.example .env

nano .env  # ⚠️ Update credentials and settings

docker compose up -d

# Verify installation
docker compose ps

Option 2: Docker Compose (Self-Build)

git clone https://github.com/goldpulpy/status-page
cd status-page
cp .env.example .env

nano .env  # ⚠️ Update credentials and settings

docker compose up -d --build

# Verify installation
docker compose ps

Option 3: Helm Chart (for Kubernetes)

• ⚠️ Review values.yaml

# Download values.yaml or use --set
mkdir -p status-page && cd status-page
wget https://raw.githubusercontent.com/goldpulpy/status-page/main/helm/values.yaml

# Install
helm install status-page oci://ghcr.io/goldpulpy/status-page \
  -f values.yaml \
  --namespace status-page \
  --create-namespace

# Verify installation
kubectl get all -n status-page

Option 4: Manual Deployment

git clone https://github.com/goldpulpy/status-page
cd status-page
make install && make build
cp .env.example .env

nano .env  # ⚠️ Update credentials and settings

make migrate
make run

Development

Make Commands

# Install all dependencies
make install

# Run development server
make run

# Build assets (JavaScript and CSS)
make build

# Code quality checks
make format        # Format code with ruff
make lint          # Lint code
make type-check    # Type checking with pyright
make security      # Security analysis with bandit

# Database operations
make migrate                    # Apply migrations
make create-migration m="..."   # Create new migration
make rollback-migration         # Rollback last migration
make migration-history          # View migration history

# Utilities
make clean         # Clean development artifacts
make requirements  # Export requirements.txt
make help          # Show all commands

PostgreSQL

Run PostgreSQL container

From the project root, execute:

docker compose -f dev/postgres/docker-compose.yaml up -d

This will start a PostgreSQL container with the configured environment.

Default configuration:

• Host: localhost
• Port: 5432
• User: root
• Password: toor
• Database: db

You can access the Adminer UI at http://localhost:8080

Select the PostgreSQL database and log in with the provided credentials.

Stop and remove PostgreSQL container

docker compose -f docker/postgres/docker-compose.yaml down

# or if you want to remove data

docker compose -f docker/postgres/docker-compose.yaml down --volumes

Database Management

# Create a migration after model changes
make create-migration m="Add user authentication"

# Apply pending migrations
make migrate

# Rollback if needed
make rollback-migration

Pre-commit Hooks

To install the pre-commit hooks:

Note: You need to have the virtual environment activated.

pre-commit install

After installation, the hooks will automatically run on every commit. If any issues are found, the commit will be blocked until they're fixed.

You can manually run all pre-commit hooks on all files with:

pre-commit run --all-files

API Documentation

Interactive API documentation is available in development mode:

• Scalar API Reference - http://localhost:5000/docs

Important

Documentation endpoints are disabled in production for security

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Run quality checks (make format lint type-check)
5. Push to your branch (git push origin feature/amazing-feature)
6. Open a Pull Request

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support

• Issues - Report bugs or request features via GitHub Issues
• Documentation - Comprehensive guides available in /docs