Getting Started

Welcome to Status Nugget! This guide will help you get up and running with your own status page in minutes.

What is Status Nugget?

Status Nugget is an open-source, self-hosted status page solution that helps you keep your users informed about the health and availability of your services and infrastructure. It provides real-time monitoring, incident management, and a beautiful, customizable interface.

Key Features

  • Real-time Monitoring: Automatically check the health of your services
  • Incident Management: Create and manage incidents with detailed updates
  • Customizable Design: Match your brand with custom themes and colors
  • Self-Hosted: Full control over your data and infrastructure
  • API Access: Integrate with your existing tools and workflows

Installation

Status Nugget can be installed in several ways. Choose the method that best fits your environment.

Prerequisites

  • Node.js 18.x or higher
  • npm 9.x or higher (or yarn/pnpm)
  • A web server (for production deployment)

Installation Methods

Using npm

Terminal 
# Clone the repository
git clone https://github.com/airforcerp/statusnugget.git
cd statusnugget

# Install dependencies
npm install

# Start the development server
npm run dev

Using Docker

Docker is the recommended way to run Status Nugget in production. It provides isolation, easy deployment, and consistent environments.

Quick Start

Terminal 
# Pull the Docker image
docker pull statusnugget/statusnugget:latest

# Run the container
docker run -d \
  -p 3000:3000 \
  -v $(pwd)/config:/app/config \
  --name statusnugget \
  statusnugget/statusnugget:latest

Advanced Docker Run Options

For production deployments, you'll want to configure additional options:

Terminal 
# Run with environment variables and resource limits
docker run -d \
  --name statusnugget \
  -p 3000:3000 \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/data:/app/data \
  -e NODE_ENV=production \
  -e PORT=3000 \
  -e DATABASE_URL=postgresql://user:pass@host:5432/dbname \
  -e SECRET_KEY=your-secret-key-here \
  --restart unless-stopped \
  --memory="512m" \
  --cpus="1.0" \
  --health-cmd="curl -f http://localhost:3000/api/health || exit 1" \
  --health-interval=30s \
  --health-timeout=10s \
  --health-retries=3 \
  statusnugget/statusnugget:latest

Environment Variables

You can configure Status Nugget using environment variables:

  • NODE_ENV - Set to production for production deployments
  • PORT - Port number for the web server (default: 3000)
  • DATABASE_URL - Database connection string
  • SECRET_KEY - Secret key for session encryption (required in production)
  • LOG_LEVEL - Logging level: debug, info, warn, error
  • REDIS_URL - Redis connection string (optional, for caching)
  • SMTP_HOST - SMTP server for email notifications
  • SMTP_PORT - SMTP port (default: 587)
  • SMTP_USER - SMTP username
  • SMTP_PASS - SMTP password

Volume Mounts

Important directories to mount as volumes:

  • /app/config - Configuration files (required)
  • /app/data - Application data and database files
  • /app/logs - Log files (optional)
  • /app/uploads - Uploaded files (if using file uploads)

Docker Image Tags

Available image tags:

  • latest - Latest stable release
  • v1.0.0 - Specific version (replace with actual version)
  • alpine - Alpine Linux-based image (smaller size)
  • dev - Development build (not recommended for production)

Building from Source

To build the Docker image from source:

Terminal 
# Clone the repository
git clone https://github.com/airforcerp/statusnugget.git
cd statusnugget

# Build the Docker image
docker build -t statusnugget:local .

# Run the locally built image
docker run -d \
  -p 3000:3000 \
  -v $(pwd)/config:/app/config \
  --name statusnugget \
  statusnugget:local

Docker Networking

For connecting to external services or databases:

Terminal 
# Create a custom network
docker network create statusnugget-network

# Run Status Nugget on the network
docker run -d \
  --name statusnugget \
  --network statusnugget-network \
  -p 3000:3000 \
  -v $(pwd)/config:/app/config \
  statusnugget/statusnugget:latest

# Connect other containers to the same network
docker network connect statusnugget-network your-database-container

Docker Health Checks

Monitor container health with built-in health checks:

Terminal 
# Check container health status
docker ps --format "table {{.Names}}\t{{.Status}}"

# View detailed health check logs
docker inspect --format='{{json .State.Health}}' statusnugget | jq

# View container logs
docker logs -f statusnugget

Updating Docker Containers

To update to a new version:

Terminal 
# Stop and remove the old container
docker stop statusnugget
docker rm statusnugget

# Pull the latest image
docker pull statusnugget/statusnugget:latest

# Run the new container with the same configuration
docker run -d \
  -p 3000:3000 \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/data:/app/data \
  --name statusnugget \
  --restart unless-stopped \
  statusnugget/statusnugget:latest

Docker Troubleshooting

Common issues and solutions:

  • Container won't start: Check logs with docker logs statusnugget
  • Port already in use: Change the port mapping: -p 3001:3000
  • Permission denied: Ensure volume paths have correct permissions
  • Out of memory: Increase Docker memory limits or add --memory flag
  • Database connection issues: Verify network connectivity and database URL

Using Docker Compose

Docker Compose simplifies multi-container deployments and is ideal for production setups with databases or other services.

Basic Docker Compose Setup

docker-compose.yml 
version: '3.8'

services:
  statusnugget:
    image: statusnugget/statusnugget:latest
    container_name: statusnugget
    ports:
      - "3000:3000"
    volumes:
      - ./config:/app/config
      - ./data:/app/data
      - ./logs:/app/logs
    environment:
      - NODE_ENV=production
      - PORT=3000
      - SECRET_KEY=${SECRET_KEY:-change-me-in-production}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    networks:
      - statusnugget-network

networks:
  statusnugget-network:
    driver: bridge

Docker Compose with PostgreSQL

Complete setup with PostgreSQL database:

docker-compose.yml 
version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    container_name: statusnugget-db
    environment:
      - POSTGRES_DB=statusnugget
      - POSTGRES_USER=statusnugget
      - POSTGRES_PASSWORD=${DB_PASSWORD:-change-me}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - statusnugget-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U statusnugget"]
      interval: 10s
      timeout: 5s
      retries: 5

  statusnugget:
    image: statusnugget/statusnugget:latest
    container_name: statusnugget
    ports:
      - "3000:3000"
    volumes:
      - ./config:/app/config
      - ./data:/app/data
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgresql://statusnugget:${DB_PASSWORD:-change-me}@postgres:5432/statusnugget
      - SECRET_KEY=${SECRET_KEY:-change-me-in-production}
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped
    networks:
      - statusnugget-network

volumes:
  postgres-data:

networks:
  statusnugget-network:
    driver: bridge

Docker Compose with Redis

Add Redis for caching and session storage:

docker-compose.yml 
version: '3.8'

services:
  redis:
    image: redis:7-alpine
    container_name: statusnugget-redis
    command: redis-server --appendonly yes
    volumes:
      - redis-data:/data
    networks:
      - statusnugget-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  statusnugget:
    image: statusnugget/statusnugget:latest
    container_name: statusnugget
    ports:
      - "3000:3000"
    volumes:
      - ./config:/app/config
    environment:
      - NODE_ENV=production
      - REDIS_URL=redis://redis:6379
      - SECRET_KEY=${SECRET_KEY:-change-me-in-production}
    depends_on:
      redis:
        condition: service_healthy
    restart: unless-stopped
    networks:
      - statusnugget-network

volumes:
  redis-data:

networks:
  statusnugget-network:
    driver: bridge

Docker Compose Commands

Common Docker Compose operations:

Terminal 
# Start all services
docker-compose up -d

# View logs
docker-compose logs -f statusnugget

# Stop all services
docker-compose down

# Stop and remove volumes
docker-compose down -v

# Restart a specific service
docker-compose restart statusnugget

# Update and restart
docker-compose pull
docker-compose up -d

# View running services
docker-compose ps

# Execute commands in container
docker-compose exec statusnugget sh

Environment File (.env)

Create a .env file for sensitive configuration:

.env 
# Database
DB_PASSWORD=your-secure-password-here

# Application
SECRET_KEY=your-secret-key-here
NODE_ENV=production
PORT=3000

# Email (optional)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-email@example.com
SMTP_PASS=your-email-password

Note: Never commit the .env file to version control. Add it to .gitignore.

Configuration

Configure Status Nugget to match your needs and branding.

Configuration File

The main configuration file is located at config/config.json. Here's a sample configuration:

config/config.json 
{
  "site": {
    "name": "My Service Status",
    "description": "Status page for our services",
    "url": "https://status.example.com",
    "logo": "/logo.png",
    "favicon": "/favicon.ico"
  },
  "server": {
    "port": 3000,
    "host": "0.0.0.0"
  },
  "monitoring": {
    "interval": 60000,
    "timeout": 5000,
    "retries": 3
  },
  "notifications": {
    "enabled": true,
    "email": {
      "enabled": false,
      "smtp": {
        "host": "smtp.example.com",
        "port": 587,
        "secure": false,
        "auth": {
          "user": "user@example.com",
          "pass": "password"
        }
      }
    }
  }
}

Environment Variables

You can also configure Status Nugget using environment variables:

  • PORT - Server port (default: 3000)
  • NODE_ENV - Environment mode (development/production)
  • DATABASE_URL - Database connection string
  • SECRET_KEY - Secret key for session encryption

Adding Services

Add services to monitor their health and availability.

Service Configuration

Services can be added through the web interface or by editing the configuration file. Each service requires:

  • Name: Display name for the service
  • URL: Endpoint to monitor
  • Type: HTTP, HTTPS, TCP, or Custom
  • Interval: How often to check (in milliseconds)

Example Service

config/services.json 
[
  {
    "id": "api",
    "name": "API Service",
    "description": "Main API endpoint",
    "url": "https://api.example.com/health",
    "type": "https",
    "interval": 60000,
    "expectedStatus": 200,
    "expectedBody": null,
    "timeout": 5000
  },
  {
    "id": "database",
    "name": "Database",
    "description": "PostgreSQL database",
    "url": "postgresql://localhost:5432/mydb",
    "type": "tcp",
    "interval": 30000
  }
]

Health Check Types

  • HTTP/HTTPS: Checks if the endpoint returns a successful status code
  • TCP: Verifies the port is open and accepting connections
  • Custom: Use custom scripts or plugins for specialized checks

Incident Management

Create and manage incidents to keep your users informed about service disruptions.

Creating an Incident

Incidents can be created through the web interface or API. When creating an incident, you can:

  • Set the affected services
  • Choose the severity level (minor, major, critical)
  • Add a description and updates
  • Set the status (investigating, identified, monitoring, resolved)

Incident Lifecycle

  1. Investigating: Issue detected, team is investigating
  2. Identified: Root cause identified, working on fix
  3. Monitoring: Fix deployed, monitoring for stability
  4. Resolved: Issue fully resolved, service restored

Incident Updates

Keep users informed by posting regular updates during an incident. Updates should include:

  • Current status and progress
  • What's being done to resolve the issue
  • Expected resolution time (if available)

API Reference

Status Nugget provides a RESTful API for programmatic access to all features.

Authentication

API requests require authentication using an API key. Include it in the request header:

Headers 
Authorization: Bearer YOUR_API_KEY

Endpoints

Get Services Status

GET /api/services 
curl -X GET https://status.example.com/api/services \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Incident

POST /api/incidents 
curl -X POST https://status.example.com/api/incidents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Service Degradation",
    "description": "Experiencing slow response times",
    "severity": "major",
    "affectedServices": ["api", "database"]
  }'

Update Service Status

PUT /api/services/:id 
curl -X PUT https://status.example.com/api/services/api \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "operational",
    "uptime": 99.9
  }'

Customization

Customize the appearance of your status page to match your brand.

Theme Configuration

Themes can be configured in the config/theme.json file:

config/theme.json 
{
  "colors": {
    "primary": "#6366f1",
    "secondary": "#8b5cf6",
    "success": "#10b981",
    "warning": "#f59e0b",
    "error": "#ef4444",
    "background": "#ffffff",
    "text": "#1f2937"
  },
  "fonts": {
    "heading": "Inter, sans-serif",
    "body": "Inter, sans-serif"
  },
  "logo": {
    "url": "/logo.png",
    "width": "200px",
    "height": "auto"
  }
}

Custom CSS

For advanced customization, you can add custom CSS by creating a public/custom.css file. This will be loaded after the default styles.

Deployment

Deploy Status Nugget to production using various platforms and methods.

Production Build

Terminal 
# Build for production
npm run build

# Start production server
npm start

Deployment Options

  • VPS/Cloud Server: Deploy on any Linux server with Node.js
  • Docker: Use Docker containers for easy deployment
  • Kubernetes: Deploy on Kubernetes clusters
  • Platform as a Service: Deploy on Heroku, Railway, or similar platforms

Reverse Proxy Setup

For production, it's recommended to use a reverse proxy like Nginx:

/etc/nginx/sites-available/statusnugget 
server {
    listen 80;
    server_name status.example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Troubleshooting

Common issues and their solutions.

Services Not Updating

  • Check that the monitoring service is running
  • Verify service URLs are accessible
  • Check firewall rules and network connectivity
  • Review logs for error messages

Database Connection Issues

  • Verify database credentials in configuration
  • Ensure database server is running
  • Check network connectivity to database
  • Review database logs for errors

Performance Issues

  • Reduce monitoring interval for less critical services
  • Increase server resources (CPU, RAM)
  • Optimize database queries
  • Enable caching where appropriate

Getting Help

If you're still experiencing issues: