KeepUp Documentation

KeepUp is an ultra-lightweight, zero-dependency uptime monitor and public status page engine written in asynchronous Rust. It compiles all frontend assets, database migrations, and alerting routines into a single binary that idles with under 15MB of RAM.

Docker Quickstart

The fastest way to deploy KeepUp in production is using the official lightweight container image (~25MB total image size):

docker run -d \
  --name keepup \
  -p 8080:8080 \
  -v ./data:/data \
  -e ADMIN_USER=admin \
  -e ADMIN_PASSWORD=supersecret \
  ridloghfry/keepup:latest
Initial Dashboard Login
Username: admin Password: admin

⚠️ Change these default credentials immediately in production by setting environment variables ADMIN_USER and ADMIN_PASSWORD.

Once started, access the two endpoints:

  • Admin Dashboard: http://localhost:8080/ (Login with your configured credentials)
  • Public Status Page: http://localhost:8080/status (Customer-facing, no authentication required)

Docker Compose

For automated deployments with persistent storage and automatic restarts, create a docker-compose.yml:

version: '3.8'

services:
  keepup:
    image: ridloghfry/keepup:latest
    container_name: keepup
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./data:/data
    environment:
      - PORT=8080
      - KEEPUP_DB_PATH=/data/keepup.db
      - ADMIN_USER=admin
      - ADMIN_PASSWORD=change_this_to_strong_password
      - JWT_SECRET=generate_a_random_32_character_secret_here
      - RUST_LOG=keepup=info

Start the container in detached mode:

docker compose up -d

Multi-Architecture Docker Builds (amd64 / arm64)

KeepUp ships official multi-architecture container images supporting both linux/amd64 (Intel/AMD) and linux/arm64 (Apple Silicon, AWS Graviton, Raspberry Pi) using cargo-chef for optimized layer caching.

Build and test multi-architecture images locally with Docker Buildx:

# Build multi-architecture container image locally
docker buildx build --platform linux/amd64,linux/arm64 -t ridloghfry/keepup:test .

# Inspect published multi-architecture manifest
docker buildx imagetools inspect ridloghfry/keepup:latest

Building from Source & Cargo

KeepUp requires Rust 1.82+ to compile. Build the release binary or install directly into your Cargo environment:

# Clone the repository
git clone https://github.com/RidloGhifary/keepup.git
cd keepup

# Option A: Compile standalone release binary
cargo build --release
./target/release/keepup

# Option B: Install directly into your Cargo binary path ($HOME/.cargo/bin)
cargo install --path .
keepup
Initial Dashboard Login
Username: admin Password: admin

⚠️ Change these default credentials immediately in production by setting environment variables ADMIN_USER and ADMIN_PASSWORD.

Environment Variables

Configure KeepUp via environment variables or a local .env file:

Variable Default Description
PORT 8080 HTTP port KeepUp listens on.
KEEPUP_DB_PATH ./data/keepup.db Filesystem path to the SQLite database file.
ADMIN_USER admin Username for dashboard authentication.
ADMIN_PASSWORD admin Password for dashboard authentication (strongly recommended to change in production).
JWT_SECRET keepup_jwt_fallback_secret_key_32bytes 32+ character HMAC secret for signing session cookies.
STATUS_PAGE_THEME auto Default status page aesthetic (auto, dark, oled, midnight, light).
CUSTOM_LOGO_URL None Optional image or SVG logo URL displayed in the status page header.
RUST_LOG keepup=info Log verbosity filter (trace, debug, info, warn, error).

Password Recovery / CLI Reset

Recovery stays local. Resetting a password requires shell access to the host or container; KeepUp does not use email recovery.

The command updates the password hash in the SQLite database selected by KEEPUP_DB_PATH, then exits without starting the web server.

Docker

Run this from the Docker host. The container must be running and attached to the same database volume used by KeepUp.

docker exec -it keepup /usr/local/bin/keepup --reset-password

Standalone binary

Run the command from the same working directory and environment used by the KeepUp service so it opens the same database.

./keepup --reset-password

The CLI prompts for the new password twice, masks terminal input, and requires at least 8 characters. After it reports success, sign in to the dashboard with ADMIN_USER and the new password. Automation can pass the new value with --password; command-line arguments may be visible to other processes.

SQLite & WAL Storage

KeepUp automatically initializes SQLite on startup with Write-Ahead Logging (PRAGMA journal_mode=WAL;) and PRAGMA synchronous=NORMAL;. This ensures high-throughput asynchronous writes from Tokio health check workers never block telemetry reads from the public status page or dashboard.

HTTP & HTTPS Probes

KeepUp supports flexible synthetic probes for web services and APIs:

  • Request Methods: GET, HEAD, POST with custom body payloads.
  • Custom HTTP Headers: Send custom User-Agent, Authorization tokens, or API keys.
  • Expected Status Code Ranges: Accepts ranges such as 200-299 or specific codes like 200,204,301.
  • Keyword Matching: Verifies that response body contains an expected string token (e.g. "status":"ok").

TCP Port Pings

Validate reachability and connection latency for databases, caching layers, and game servers (Postgres 5432, Redis 6379, SSH 22) using raw asynchronous TCP socket handshakes.

Failure & Retry Logic

To prevent false positive alerts caused by brief transient network blips, KeepUp tracks state transition counts. A service must fail consecutive checks equal to its configured max_retries (default: 3) before triggering a state change from UP to DOWN.

Scheduled Maintenance Windows

KeepUp allows operations teams to schedule upcoming downtime or maintenance windows in advance. When a window becomes active:

  • Announcement Banners: A prominent announcement banner is displayed at the top of all public status pages with title, description, and exact window timing.
  • Component Status Badges: Monitors linked to the maintenance window switch to an explicit MAINTENANCE state with distinct purple accent badges (#A855F7).
  • Incident Isolation: Expected downtime does not trigger incident alerts or degrade public reliability scores.

Alert Suppression Rules

During active maintenance windows, KeepUp automatically suppresses webhook alerts (Discord, Slack, Generic Webhook) for all covered monitors.

The background scheduler evaluates active windows dynamically during each check execution. If a target fails while its maintenance window is active (start_time ≤ now ≤ end_time), state transition notifications are paused. Once the maintenance window expires, regular alerting thresholds and recovery alerts resume seamlessly without manual operator intervention.

Maintenance REST API

Maintenance windows can be created, updated, and canceled via the administrative REST API:

# Schedule a maintenance window
curl -X POST http://localhost:3000/api/admin/maintenance \
  -H "Content-Type: application/json" \
  -H "Cookie: keepup_session=<jwt_cookie>" \
  -d '{
    "title": "Database Engine Migration",
    "description": "Routine database maintenance and schema migrations.",
    "start_time": "2026-11-01T02:00:00Z",
    "end_time": "2026-11-01T04:00:00Z",
    "monitor_ids": ["mon_db_primary", "mon_api_gateway"]
  }'

Available maintenance endpoints:

  • GET /api/admin/maintenance — List all active, scheduled, and past maintenance windows.
  • POST /api/admin/maintenance — Schedule a new maintenance window.
  • PUT /api/admin/maintenance/:id — Update time bounds, description, or attached monitors.
  • DELETE /api/admin/maintenance/:id — Delete or cancel a scheduled maintenance window.

Discord Embeds

KeepUp delivers rich Discord embeds with high-contrast status colors and detailed incident diagnostic fields:

  • Operational / Resolved: Status Green (0x30D158 / #30D158)
  • Outage / Downtime: Status Red (0xFF453A / #FF453A)
  • Scheduled Maintenance: Maintenance Purple (0xA855F7 / #A855F7)
{
  "embeds": [{
    "title": "🔴 Production API Gateway is DOWN",
    "color": 16729402,
    "fields": [
      { "name": "Service", "value": "Production API Gateway", "inline": true },
      { "name": "Status", "value": "DOWN", "inline": true },
      { "name": "Target URL", "value": "https://api.example.com/health", "inline": false },
      { "name": "Latency", "value": "N/A", "inline": true },
      { "name": "HTTP Status", "value": "502", "inline": true },
      { "name": "Error Details", "value": "HTTP 502 Bad Gateway", "inline": false }
    ],
    "timestamp": "2026-10-31T12:00:00Z",
    "footer": { "text": "KeepUp Uptime Monitor" }
  }]
}

Slack Block Kit

Slack notifications use structured Block Kit cards featuring dynamic status icons (:white_check_mark: for UP, :rotating_light: for DOWN, :wrench: for MAINTENANCE), diagnostic fields, and outage duration metrics:

{
  "blocks": [
    {
      "type": "header",
      "text": { "type": "plain_text", "text": "🚨 *Production API Gateway* is *DOWN*", "emoji": true }
    },
    {
      "type": "section",
      "fields": [
        { "type": "mrkdwn", "text": "*Monitor:*\nProduction API Gateway" },
        { "type": "mrkdwn", "text": "*Status:*\nDOWN" },
        { "type": "mrkdwn", "text": "*Target URL:*\nhttps://api.example.com/health" },
        { "type": "mrkdwn", "text": "*Response Time:*\n142 ms" }
      ]
    },
    {
      "type": "context",
      "elements": [{ "type": "mrkdwn", "text": "*Error:* HTTP 502 Bad Gateway" }]
    },
    { "type": "divider" },
    {
      "type": "context",
      "elements": [{ "type": "mrkdwn", "text": "Sent by *KeepUp* uptime monitor" }]
    }
  ]
}

Generic Webhooks

For custom webhook integrations, Opsgenie, or incident response platforms, KeepUp dispatches structured JSON payloads for status transitions and recoveries:

// Outage Alert (DOWN)
{
  "event": "status_change",
  "monitor_id": "mon_01h8",
  "monitor_name": "Production API Gateway",
  "target_url": "https://api.example.com/health",
  "status": "DOWN",
  "response_time_ms": 142,
  "http_status": 502,
  "timestamp": "2026-10-31T12:00:00Z"
}

// Resolution Alert (UP)
{
  "event": "monitor.recovered",
  "monitor_id": "mon_01h8",
  "monitor_name": "Production API Gateway",
  "target_url": "https://api.example.com/health",
  "status": "UP",
  "downtime_duration_secs": 860,
  "response_time_ms": 28,
  "timestamp": "2026-10-31T12:14:20Z"
}

Recovery Notifications

When a failing service recovers, KeepUp automatically calculates the exact downtime duration (e.g., "Downtime: 14 minutes, 20 seconds") and sends a resolution alert ([RESOLVED]) across configured channels.

Multi-Status Pages & Custom Slugs

KeepUp supports multi-tenant public status pages served on custom URL slugs (/status/:slug), allowing organizations to maintain isolated dashboards for different services, departments, or customer tiers (e.g. /status/api, /status/core, /status/internal).

The default status page at /status renders the default slug configuration, or falls back to showing all active monitors if unconfigured.

Monitor Grouping & Categorization

Monitors can be organized into distinct visual categories (such as “REST Endpoints”, “Databases”, or “Background Workers”) with explicit display ordering.

# Create a custom status page with categorized monitor assignments
curl -X POST http://localhost:3000/api/admin/status-pages \
  -H "Content-Type: application/json" \
  -H "Cookie: keepup_session=<jwt_cookie>" \
  -d '{
    "slug": "api",
    "title": "API Systems Health",
    "description": "Real-time performance of public REST APIs and Webhook services",
    "is_public": true,
    "monitors": [
      { "monitor_id": "mon_01", "group_name": "REST Endpoints", "display_order": 0 },
      { "monitor_id": "mon_02", "group_name": "Webhooks", "display_order": 1 }
    ]
  }'

7-Day Uptime Timeline

The public status page renders a responsive 7-day interactive history bar for each public component. Each day represents the aggregated operational uptime percentage with tooltips showing exact percentages.

24-Hour Latency Chart

Monitors display a 24-slot hourly latency breakdown chart representing the past 24 hours chronologically. Bar heights scale proportionally to response latency, and bar colors reflect operational health.

Latency Percentiles (P50, P95, P99)

Beyond simple hourly averages, KeepUp computes precise response time percentiles directly from SQLite check history:

  • P50 (Median): 50% of requests experienced lower latency than this metric. Represents typical real-world response speeds.
  • P95 Tail Latency: 95% of checks responded faster than this threshold. Essential for identifying degradation under moderate traffic.
  • P99 Outlier Latency: 99% of requests completed faster than this time. Highlights extreme edge latency during GC pauses or network congestion.
  • 24-Hour Average: Weighted mean response time across all successful checks in the last 24 hours.

Percentiles are calculated in-memory over sorted check logs for high computational speed without heavy time-series dependencies:

// Exposed in /api/public/status and /api/public/status/:slug
"latency": {
  "p50": 34,
  "p95": 89,
  "p99": 142,
  "avg": 41
}

Theme Customization

KeepUp status pages support 4 built-in aesthetic themes:

  • System Dark (default): Deep dark #0b0b0c canvas with glassmorphic cards.
  • OLED Pitch Black: Pure #000000 high-contrast styling for OLED displays.
  • Midnight Navy: Deep navy #050B14 background with subtle cyan glass borders.
  • Clean Light: Clean light gray #F5F5F7 styling with white translucent cards.

Visitors can toggle themes manually via the Sun/Moon button, or let the page match their OS mode via prefers-color-scheme.

Vector Status Badges

KeepUp generates dynamic, standalone SVG status badges served with zero runtime dependencies via /api/public/badge/:monitor_id.svg:

Status Hex Code Badge Preview
Operational (UP) #30D158 Green
Downtime (DOWN) #FF453A Red
Maintenance #A855F7 Purple
Degraded #FFD60A Yellow
Unknown / Not Found #71717A Gray

Embed badges directly into GitHub READMEs, markdown documentation, or company portals:

<!-- Markdown Format -->
![API Status](https://status.example.com/api/public/badge/mon_api_gateway.svg)

<!-- HTML Format -->
<img src="https://status.example.com/api/public/badge/mon_api_gateway.svg" alt="Service Status">

Async Tokio Runtime

KeepUp's health check scheduler runs within Tokio's multi-threaded asynchronous runtime. Check workers run concurrently without blocking HTTP serving or database updates.

Security & Rate Limiting

KeepUp protects the admin dashboard against credential brute-forcing using tower-governor. Authentication utilizes constant-time string comparisons via the subtle crate, and issues 7-day signed HttpOnly, SameSite=Lax JWT session cookies.