Skip to content
NorthplaneNorthplane

Quickstart

This page gets you from nothing to a running instance with one monitored host, one HTTPS service and a working notification channel. It deliberately takes shortcuts (plain HTTP on your own machine, a public ntfy topic); Installation covers the production variants and First steps continues with templates, the alarm chain, API tokens and the agent.

You need one of: Docker, Docker Compose, or a northplaned binary for Linux/macOS (amd64/arm64). The one-line installer fetches the newest release tarball; the container image is ghcr.io/myfoxit/northplane — both public, no login needed. Building from source (make all) is the third option (Installation).

1. Start the server

Section titled “1. Start the server”

The image runs northplaned serve as the distroless nonroot user (uid 65532) with NORTHPLANE_LISTEN=:8443 and NORTHPLANE_DATA_DIR=/var/lib/northplane. Because :8443 is a non-loopback listener, the server refuses to start without TLS unless you explicitly allow plaintext for a local trial:

Terminal window
docker run -d --name northplane \
  -p 8443:8443 \
  -v northplane-data:/var/lib/northplane \
  -e NORTHPLANE_TLS_INSECURE=true \
  -e NP_DEFAULT_ADMIN_DISABLED=1 \
  ghcr.io/myfoxit/northplane:latest
docker logs -f northplane

Open http://localhost:8443/setup. The log shows northplane: listening addr=:8443 scheme=http storage=sqlite followed by first run: open http://127.0.0.1:8443/setup to create your admin account.

  • NORTHPLANE_TLS_INSECURE=true allows plain HTTP on the non-loopback listener. Without it the container exits with no TLS configured on a non-loopback listener — set tls.certFile/keyFile, or trustProxy behind a TLS-terminating proxy, or tls.insecure for dev. Never publish such a port beyond your machine — use the Compose stack or real certificates instead.
  • NP_DEFAULT_ADMIN_DISABLED=1 keeps the interactive /setup page open (see step 2 for why).
  • The named volume northplane-data holds the SQLite database, the event segments, the NP-TSDB and the auto-generated secret.key. A bind mount must be writable by uid 65532.

2. Create the admin account

Section titled “2. Create the admin account”

There are two ways to get the first administrator, and which one you get depends on one environment variable:

  • Interactive /setup — the page is open only while the instance has no local user and no API token. On every start, northplaned serve also runs the default-admin seeding: unless NP_DEFAULT_ADMIN_DISABLED is set to any non-empty value (or NP_DEFAULT_ADMIN_PASSWORD is set to an empty string), it creates a local admin admin@localhost when no enabled local admin exists. That local user closes /setup before you ever see it — which is why the commands above set NP_DEFAULT_ADMIN_DISABLED=1. Fill in name, e-mail, a password of at least 12 characters and the confirmation; you are logged in as admin immediately.
  • Seeded break-glass admin — leave the seeding enabled and read the one-time log line seeded default admin with a GENERATED password — save it now, it is not recoverable (fields email=admin@localhost, password=<32 hex chars>), or choose your own credentials with NP_DEFAULT_ADMIN_EMAIL, NP_DEFAULT_ADMIN_PASSWORD and optionally NP_DEFAULT_ADMIN_NAME. Then log in at /login. The login page is German: E-Mail, Passwort, Anmelden.

Headless alternative: northplaned bootstrap-admin -config <path> mints an API token with scope *:* (printed once) — creating any token also closes /setup. Details: Authentication.

3. Add a host and an HTTPS service

Section titled “3. Add a host and an HTTPS service”

  1. In the sidebar open Objects (Objekte) and click New host (Host anlegen). On the Basics (Basis) tab enter Name example-web and Address example.org.

  2. Switch to the Check (Prüfung) tab. A new object starts as passive (no active check), so set the check command kind to builtin and type icmp in the builtin-check field. Leave the interval and retry settings at their defaults (60 s, 15 s, 3 attempts, 30 s timeout) and Save (Speichern).

  3. Click New service (Service anlegen): Name https, Host example-web. On the Check tab choose builtin / http and add the arguments one per entry: -u, https://example.org/, -w, 1, -c, 3. The built-in http/https check only uses TLS when -S is given or -u is a full https:// URL, so pass the full URL. Save.

  4. Both rows show PENDING (AUSSTEHEND) until the first result. The scheduler runs a new object within one interval; hover a row and click Check now (Jetzt prüfen) to force it. The host turns UP and the service OK with an output like HTTP OK - 200 OK https://example.org/ in 0.123s, 1234 bytes, cert expires in 80d.

  5. Click the service row: the detail page shows state, last/next check, perfdata meters (time, size, cert_days) and, after a few results, a chart from the NP-TSDB. The Configuration (Konfiguration) tab shows the effective spec with every default resolved.

The same two objects as a YAML bundle, for np apply or Admin → Config bundles:

quickstart.yaml
kind: Host
metadata:
  name: example-web
spec:
  address: example.org
  checkCommand: builtin:icmp
---
kind: Service
metadata:
  name: https
  host: example-web
spec:
  checkCommand: builtin:http
  args: ["-u", "https://example.org/", "-w", "1", "-c", "3"]

4. Send a test notification

Section titled “4. Send a test notification”

  1. Open Admin → Channels (Kanäle) and click Create (Anlegen). Choose Type ntfy, Name ntfy, keep Enabled (Aktiv) on, set Server URL https://ntfy.sh and a Topic nobody will guess, e.g. northplane-7f3a9c2d. Save.

  2. In the channel row click Send test (Test senden). The server posts a synthetic info alert titled Test notification from Northplane (<your name>) to the topic and the row shows ✓ sent; a failure shows the transport error instead.

  3. Open https://ntfy.sh/northplane-7f3a9c2d in another tab (or the ntfy app) — the message is there. ntfy.sh topics are public, so treat the topic name as a secret or run your own ntfy server.

Any channel type can be tested the same way; for types that deliver to a contact target (e-mail, SMS, voice, push) the UI button sends without a target, so use the API with one:

Terminal window
curl -X POST http://127.0.0.1:8443/api/v1/channels/ntfy:test-notification \
  -H "Authorization: Bearer $NP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"target": "[email protected]"}'

($NP_TOKEN is an API token from Admin → API tokens or northplaned bootstrap-admin; the endpoint needs config:write.) Channel reference: Channels.

5. Where to go next

Section titled “5. Where to go next”
  • First steps — the UI tour, templates, a complete channel → contact → escalation policy → rule chain, API tokens and np, installing np-agent.
  • Demo mode — northplaned serve --demo seeds a full showcase (hosts, checks, alerts, on-call, dashboard, report, two demo users) in a separate data directory.
  • Installation — northplaned init with a systemd unit, TLS, PostgreSQL, Compose with Let’s Encrypt, building from source.
  • Deployment overview — which variant fits which environment, and the ports you may need to open.