Getting Started

Overview

Netra Uptime is an open-source, self-hosted uptime monitoring and incident management platform built with Go and SvelteKit. It packages the concurrent Go worker pool and compiled SvelteKit frontend into a single binary or container image, backed by either PostgreSQL 16 or embedded pure-Go SQLite with Write-Ahead Logging (WAL).

With built-in thread-safe in-memory caching and sliding-window rate limiting (cache.MemoryCache), Netra Uptime has zero external cache dependencies. It monitors websites, APIs, and infrastructure with multi-protocol checks (HTTP/HTTPS, TCP, and unprivileged Ping), tracks SSL and domain expiration, and routes alerts to Slack, Discord, Email, or custom webhooks.

Quick Start via CLI

Run Netra Uptime with a single command using the official CLI runner. It initializes your .env and docker-compose.yml configurations with secure random credentials in ~/.netra-uptime and starts the production 2-service stack (postgres + netra-uptime).

Instant Run (No Installation Required)

npx pnpm yarn bun

$ npx netra-uptime start Copy

Global Installation (Optional)

If you prefer having the netra-uptime command permanently available in your terminal, install it globally and run netra-uptime start anywhere:

npm pnpm yarn bun

$ npm install -g netra-uptime Copy

Manual Setup

If you prefer manual configuration without the CLI runner, clone the repository directly from GitHub and start Docker Compose:

git clone https://github.com/Xuerns/Netra-Uptime.git /opt/netra-uptime
cd /opt/netra-uptime && cp .env.example .env
docker compose up -d

CLI Command Reference

The Netra Uptime CLI manages container lifecycle, database credentials, and service logs in your workspace directory (defaults to ~/.netra-uptime):

CLI Flags & Options

• --port <n> — Host port for the web dashboard (default: 27346).
• --dir <path> — Installation and workspace directory (default: ~/.netra-uptime).
• --force — Overwrite existing .env and docker-compose.yml during init.

Standalone Binary (SQLite)

In addition to Docker Compose, Netra Uptime can run as a single standalone executable with pure-Go embedded SQLite. In this mode, no PostgreSQL or Docker runtime is needed—the entire application, database engine, web assets, and worker routines execute within a single lightweight process.

Download for Windows

1. 1
   Move it to a dedicated folder For example C:\NetraUptime. The database (netra.db), secret key, and logs are stored next to the executable, so avoid running it from Downloads.
2. 2
   Double-click netra-uptime.exe The dashboard opens automatically in your browser at http://localhost:27346 and Netra Uptime keeps running in the system tray.
3. 3
   Create your account Register your first account in the dashboard. Use the tray icon to reopen the dashboard (Open Netra) or stop the service (Quit).

Background Desktop Features & Flags

The Windows desktop binary includes built-in background management designed for system startup and seamless desktop integration:

• --background — Launches Netra Uptime silently in the system tray without opening a browser window or console popup. Ideal when placing a shortcut inside the Windows Startup folder (shell:startup).
• --no-browser — Prevents the web browser from opening automatically on startup, allowing you to access the dashboard manually at your convenience.
• Single-Instance Mutex Guard — Uses a Windows named mutex (Local\NetraUptimeSingleInstanceMutex) to guarantee that only one instance of Netra Uptime runs at any time. If you double-click the executable or shortcut while Netra Uptime is already active, the new process detects the running instance, focuses the existing browser tab, and terminates cleanly without causing port conflicts or duplicate workers.

Optional Configuration

The executable runs with zero configuration: it defaults to SQLite on 127.0.0.1:27346. To customize it, place a .env file next to the executable:

PORT=27346
APP_ENV=production
DB_DRIVER=sqlite
DB_PATH=netra.db
ALLOWED_ORIGIN=http://localhost:27346
PUBLIC_API_URL=/api/v1

Build from Source (Advanced)

Only needed for Linux and macOS binaries or when contributing. Requires Go and pnpm:

# Linux / macOS (Pure-Go binary)
cd server && go build -tags netgo -ldflags="-s -w" -o netra-uptime ./cmd/netra-uptime
./netra-uptime

# Windows PowerShell build script
.\scripts\build-windows.ps1
.\netra-uptime.exe

When started with DB_DRIVER=sqlite, the engine automatically configures SQLite Write-Ahead Logging (PRAGMA journal_mode=WAL), sets busy timeout to 5000ms, and pools connections safely with MaxOpenConns(1). If JWT_SECRET is not provided, Netra Uptime generates and persists a cryptographic 64-character hex secret in .netra_secret automatically.

Verifying Services & Healthcheck

Once Netra Uptime is running, the web dashboard is accessible at http://localhost:27346. Verify service health and container status with the following commands:

# Check container status
netra-uptime status

# Verify health endpoint
curl -s http://localhost:27346/healthz
# Expected output:
# {
#   "status": "ok",
#   "database": "connected",
#   "db_driver": "postgres",
#   "app_mode": "selfhosted",
#   "timestamp": "2026-10-04T12:00:00Z"
# }

# View container logs
netra-uptime logs

Next Steps

After your instance is up and running, configure your monitoring environment:

• Create Your First Monitor — Set up HTTP, TCP, or Ping monitors to begin tracking your services.
• Configure Notifications — Connect Discord, Slack, Email, or custom webhook endpoints for incident delivery.
• Set Up Alert Rules — Define latency thresholds and consecutive failure counts in reusable alert templates.
• Create a Status Page — Publish 90-day uptime history and maintenance schedules on a public status page.