Statping-ng Status Page Installation

Statping-ng is a self-hosted service monitoring and status page tool that checks your services continuously and displays uptime metrics on a public dashboard. This guide covers deploying Statping-ng on Linux with Docker, configuring service monitors, setting up notification channels, and using the API.

Prerequisites

  • Ubuntu 20.04/22.04 or CentOS 8/Rocky Linux 8+
  • Docker and Docker Compose (for Docker install)
  • At least 512 MB RAM
  • A domain name for the public status page (recommended)
  • SMTP credentials or a webhook URL for notifications

Install with Docker

Docker is the recommended method for running Statping-ng:

# Create project directory
mkdir -p /opt/statping && cd /opt/statping

# Create docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3.7'
services:
  db:
    image: postgres:14-alpine
    environment:
      POSTGRES_USER: statping
      POSTGRES_PASSWORD: statpingpassword
      POSTGRES_DB: statping
    volumes:
      - db_data:/var/lib/postgresql/data
    restart: unless-stopped

  statping:
    image: adamboutcher/statping-ng:latest
    ports:
      - "8080:8080"
    environment:
      - DB_CONN=postgres
      - DB_HOST=db
      - DB_PORT=5432
      - DB_USER=statping
      - DB_PASS=statpingpassword
      - DB_DATABASE=statping
      - NAME=My Status Page
      - DESCRIPTION=Service Status Monitor
      - ADMIN_USER=admin
      - ADMIN_PASSWORD=changeme123
      - [email protected]
    volumes:
      - statping_data:/app
    depends_on:
      - db
    restart: unless-stopped

volumes:
  db_data:
  statping_data:
EOF

# Start the stack
docker-compose up -d

# Check logs
docker-compose logs -f statping

After startup, access the dashboard at http://your-server:8080.

Install on Bare Metal

For a direct binary installation:

# Download the latest release
STATPING_VER=$(curl -s https://api.github.com/repos/statping-ng/statping-ng/releases/latest | grep tag_name | cut -d '"' -f4)
wget "https://github.com/statping-ng/statping-ng/releases/download/${STATPING_VER}/statping-linux-amd64.tar.gz"

# Extract and install
tar -xzf statping-linux-amd64.tar.gz
chmod +x statping
sudo mv statping /usr/local/bin/

# Verify
statping version

# Create a data directory
sudo mkdir -p /opt/statping
sudo useradd -r -d /opt/statping -s /bin/false statping
sudo chown statping:statping /opt/statping

# Create environment config
sudo -u statping cat > /opt/statping/.env << 'EOF'
NAME=My Status Page
DESCRIPTION=Real-time service monitoring
ADMIN_USER=admin
ADMIN_PASSWORD=changeme123
[email protected]
DB_CONN=sqlite
EOF

# Create systemd service
cat > /etc/systemd/system/statping.service << 'EOF'
[Unit]
Description=Statping-ng Status Page
After=network.target

[Service]
Type=simple
User=statping
WorkingDirectory=/opt/statping
ExecStart=/usr/local/bin/statping --port 8080
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now statping
sudo systemctl status statping

Configure Service Monitoring

Statping-ng supports HTTP, TCP, UDP, gRPC, and ICMP monitors:

# Use the API to create services
API_URL="http://localhost:8080/api"
API_KEY="your-api-key"  # Found in Settings > API

# Create an HTTP service monitor
curl -X POST "${API_URL}/services" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Website",
    "domain": "https://example.com",
    "type": "http",
    "method": "GET",
    "expected_status": 200,
    "interval": 30,
    "timeout": 10,
    "check_ssl": true,
    "notify_after": 2
  }'

# Create a TCP port check
curl -X POST "${API_URL}/services" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Database Port",
    "domain": "db.example.com",
    "type": "tcp",
    "port": 5432,
    "interval": 60,
    "timeout": 5,
    "notify_after": 1
  }'

# Create an ICMP (ping) check
curl -X POST "${API_URL}/services" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gateway Ping",
    "domain": "10.0.0.1",
    "type": "icmp",
    "interval": 30,
    "timeout": 5
  }'

# List all services and their status
curl "${API_URL}/services" \
  -H "Authorization: Bearer ${API_KEY}" | python3 -m json.tool

Via the web dashboard:

  1. Go to Dashboard > Services > Add Service
  2. Enter the service name, URL/host, check type, and interval
  3. Set the expected HTTP status code for HTTP checks
  4. Enable SSL verification for HTTPS services
  5. Configure failure threshold before alerting (Notify After)

Notification Channels

Configure notifiers in Dashboard > Settings > Notifications:

# Create a Slack notification via API
curl -X POST "${API_URL}/notifiers/slack" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "host": "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
  }'

# Create email notifier (SMTP)
curl -X POST "${API_URL}/notifiers/email" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "host": "smtp.sendgrid.net",
    "port": 587,
    "username": "apikey",
    "password": "your-sendgrid-key",
    "var1": "[email protected]",
    "var2": "[email protected]"
  }'

# Test a notifier
curl -X POST "${API_URL}/notifiers/slack/test" \
  -H "Authorization: Bearer ${API_KEY}"

Available notifiers include:

  • Slack - Webhook-based channel notifications
  • Discord - Webhook notifications
  • Email - SMTP delivery
  • Telegram - Bot API messages
  • PagerDuty - On-call escalation
  • Webhook - Custom HTTP callbacks

Custom Themes and Branding

# Access theme settings at Dashboard > Settings > Theme
# Statping-ng uses SCSS-based themes

# Create a custom theme file
cat > /opt/statping/assets/scss/custom.scss << 'EOF'
// Custom brand colors
$primary: #2563eb;
$secondary: #64748b;
$success: #16a34a;
$danger: #dc2626;

body {
  font-family: 'Inter', sans-serif;
}

.navbar {
  background-color: $primary !important;
}
EOF

# Upload a custom logo via the dashboard:
# Settings > General > Logo URL
# Paste the URL to your logo image

# Customize the page description and footer
# Settings > General > Description and Footer

API Usage

# Authenticate and get a token
curl -X POST "${API_URL}/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "changeme123"}'

# Get status overview
curl "${API_URL}/services" | python3 -m json.tool

# Get uptime statistics for a service (ID=1)
curl "${API_URL}/services/1/uptime/48h" \
  -H "Authorization: Bearer ${API_KEY}"

# Get failure log for a service
curl "${API_URL}/services/1/failures" \
  -H "Authorization: Bearer ${API_KEY}"

# Get all incidents
curl "${API_URL}/incidents" | python3 -m json.tool

# Create an incident
curl -X POST "${API_URL}/incidents" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Elevated Error Rates",
    "description": "We are investigating elevated error rates on the API gateway.",
    "service": 1
  }'

# Create a maintenance window
curl -X POST "${API_URL}/incidents" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Scheduled Maintenance",
    "description": "System maintenance from 02:00 to 04:00 UTC.",
    "service": 0
  }'

Nginx Reverse Proxy Setup

# Install Nginx and Certbot
sudo apt install -y nginx certbot python3-certbot-nginx

# Create Nginx config
cat > /etc/nginx/sites-available/statping << 'EOF'
server {
    listen 80;
    server_name status.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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_read_timeout 60s;
    }
}
EOF

sudo ln -s /etc/nginx/sites-available/statping /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

# Obtain SSL certificate
sudo certbot --nginx -d status.example.com

Troubleshooting

Service shows as offline but is actually up:

# Check if Statping-ng can reach the service from the server
curl -I https://example.com
ping -c 4 db.example.com

# Adjust timeout settings (increase if network is slow)
# Dashboard > Edit Service > Timeout

# Check Statping-ng logs
docker-compose logs statping --tail 50
# or for bare metal:
journalctl -u statping -n 50

Database connection errors on startup:

# For Docker: ensure db is healthy before statping starts
docker-compose ps
docker-compose restart statping

# For PostgreSQL: test connection manually
psql -h localhost -U statping -d statping -c "\l"

Dashboard shows no data after restart:

# Verify the data volume is mounted correctly
docker inspect statping_statping_1 | grep Mounts -A 20

# Check SQLite database exists (bare metal)
ls -lh /opt/statping/statping.db

Cannot log in to dashboard:

# Reset admin password via CLI
statping --reset-password admin newpassword123

# Or via Docker
docker-compose exec statping statping --reset-password admin newpassword123

Conclusion

Statping-ng is a lightweight, self-hosted monitoring and status page solution that supports multiple check types and notification channels with minimal resource requirements. Deploy it with Docker Compose for the easiest setup, configure service checks via the web dashboard or API, and expose it through an Nginx reverse proxy with SSL for a professional public status page.