Complete user manual

Install SignalHub and finish setup in the browser

SignalHub needs one thing from outside: a PostgreSQL 14+ database. On first start it has no database and no administrator, so it serves only the setup wizard at /setup. Every other page redirects there until setup is finished.

Choose how to run it

With Node.js, start:all runs migrations, the web server and the background worker under one supervisor. It listens on 127.0.0.1:3301 by default (change with PORT and SIGNALHUB_HOST) and keeps its setup file in ./data (SIGNALHUB_DATA_DIR). In development, npm run dev and npm run dev:all open the wizard when .env has no DATABASE_URL; with one, they migrate and start as before. npm run dev:web is the bare Next.js dev server.

Setup wizard

1. Database. Enter host, port, database, user, password and encryption mode, or paste a connection URL (a custom CA can be pasted for RDS, Azure or Cloud SQL). Test connection explains problems in plain language. If the server is reachable but the database does not exist, Create database creates it. Confirm the public URL and save; the schema is installed and the page continues on its own.
2. Administrator. Organization name and ID, your name, email, User ID and password. This account administers the organization and the whole installation. Download the configuration backup offered here: it holds the encryption key.
3. Done. Sign in at /login.

Restart setup

• In the wizard: before the administrator exists, Wrong database? Start over with a different one returns to the database step. Nothing in that database is deleted.
• From the command line: signalhubctl setup --reset forgets the saved connection and keeps the secrets. The next start runs the wizard again.

Forgotten passwords

From first login to a working status page

SignalHub separates public status experiences from the authenticated organization console. Operators sign in at /login and use canonical console URLs under /organization. Visitors use a page slug, hub, feed, embed, badge, or public API.

First Admin login

1. Open https://your-signalhub-host/login and sign in with the administrator account created in the setup wizard (or the user ID and password supplied by the installation operator).
2. Change the temporary password. If a profile field is required, complete it before continuing.
3. If your installation requires authenticator codes you are taken through MFA setup right after the password: scan the QR code, confirm a code and save the recovery codes offline. Then open Security (the shield in the sidebar footer) and verify the session list.
4. Open Platform administration → Configuration → Organization and confirm the organization name, slug, contact address and retention expectations. Check database, migration and worker health under Configuration → Runtime, and review Security → Identity for sign-in methods.
5. Open Pages → Create page. Choose a status page unless you are building a portfolio hub.
6. Complete page details, add at least one visible service, review appearance, configure optional notifications, and publish.
7. Use View public page in a private browser window. Confirm the page, history, subscription controls, and mobile layout.
8. Create a test incident, add an update, resolve it, and verify public history and enabled destinations.

Before production use

Give each person only the access they need

Non-Admin memberships can be limited to selected page IDs. Page scope applies on the server and affects pages, incidents, monitors, metrics, and other page-owned resources. An empty page selection means all pages for that membership.

What every organization menu is for

Design the right status experience for each audience

Choose the page type

Page creation and publication

1. Open Pages → Create page, select page or hub, choose a stable slug, and optionally assign a parent hub.
2. Open Services & groups. Add or manage groups from the Group field. Select the green save icon to publish a changed service status. Drag a six-dot handle to reorder; dropping saves automatically, including on filtered or paginated lists. Choose Page order and turn off grouping first. For a hub, create or attach child pages.
3. Open Appearance. Choose a Standard, Banner, or Compact layout, then pick a style tile (each tile previews its colors), adjust the brand color, add footer links and search details, and upload a logo, site icon, and optional cover image. Changes autosave as a draft until you select Publish changes.
4. For private or audience pages, open Access and configure allowed identities/groups and component scope. Test with a non-Admin account.
5. Open Notifications to review subscriber channels, set the email sender name, reply-to address, and footer, and manage team destinations and webhooks.
6. Open the page's Settings tab to set the page name, headline, about text, time zone (used for dates and maintenance windows), search-engine indexing, and destructive controls.
7. Publish from the overview. A status page needs at least one visible service; a hub can publish its page directory.

Page-management tabs

Communicate unplanned disruption with a durable timeline

Declare an incident

1. Confirm the affected customer experience. Do not wait for complete root-cause certainty before acknowledging a clear impact.
2. Open Events → Declare incident, choose the page, and enter a plain-language title.
3. Select status, severity/impact, affected services, and the first public update. State what users observe, what the team is doing, and when the next update is expected.
4. Review whether subscriber notifications should be sent. Publish and verify the public page and delivery history.

Update cadence

• Investigating: acknowledge symptoms and scope; avoid unsupported causes.
• Identified: explain the known cause or failing dependency and mitigation underway.
• Monitoring: report the mitigation and what signals are being watched.
• Resolved: state restoration time, customer outcome, and whether a postmortem will follow.

Add a new update when state, impact, workaround, scope, or estimated recovery changes. If nothing changes, keep the promised cadence and say the investigation continues.

Edit timeline and publish a postmortem

Authorized users can correct an update while preserving the incident's durable chronology. Use edits for accuracy, not to hide operational history. After resolution, add a postmortem with impact, timeline, cause, contributing conditions, recovery, corrective actions, owners, and target dates.

Set expectations before planned work begins

1. Open Events → Schedule maintenance, choose a page, title, start time, duration, and clear customer-facing description.
2. Select affected services and the status they should display, normally Under Maintenance.
3. Enable automatic transition when the worker should move the window to In Progress at the start and Completed at the end.
4. Publish early enough for subscribers to plan. Verify timezone presentation and enabled delivery channels.
5. At start, confirm the real work matches the announced scope. If impact becomes unexpected or exceeds the plan, open an incident.
6. At completion, verify service health and public component state before closing the window.

Detect failure without creating noisy public status changes

Create and tune a monitor

1. Select the page, monitor type, target, interval, timeout, tags/group, and optional service.
2. Set failure and recovery thresholds. Requiring consecutive outcomes prevents one transient check from flipping state.
3. Save with automated component action disabled when possible. Use Check on next poll and inspect results, latency, and error detail.
4. Enable component synchronization only after the monitor reliably represents customer impact.
5. Alert operators on stale worker heartbeat, missing checks, and repeated monitor errors.

Metrics

Metrics are numeric time series displayed on a status page. Create a name, optional unit suffix, and optional component link. Push points manually for validation or through POST /api/v1/manage/metrics/<id>/points. A chart appears publicly after it has data. Metrics explain performance; monitors determine check state.

Send the right update through verified channels

Subscriber workflow

Visitors request a one-time code and verify ownership before activation. Administrators use Subscribers to filter by page/channel, import approved email contacts, quarantine a contact without deleting it, and export CSV. Treat subscriber contact information as protected operational data.

Delivery troubleshooting order

1. Confirm the worker is ready and recently heartbeating.
2. Confirm the provider is enabled in installation configuration.
3. Confirm tenant credentials and destination verification state.
4. Inspect the queued attempt, retry schedule, last error, and dead-letter state.
5. Send a controlled test before replaying a broad set of deliveries.

Automate with scoped credentials, not browser sessions

Management API keys

1. Open Platform administration → Security → API keys, select the page context, name the integration, and choose only required scopes.
2. Add page restrictions, expiration, and source CIDRs where practical.
3. Copy the token once into a secret manager. SignalHub stores its hash and cannot show the full token again.
4. Send Authorization: Bearer <token> to /api/v1/manage/*.
5. Rotate before expiry or immediately after suspected exposure; revoke the old key and verify audit evidence.

curl -fsS https://status.example.com/api/v1/manage/incidents \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  --data '{"pageId":"<page-id>","name":"Elevated API errors","status":"INVESTIGATING","impact":"MINOR","body":"We are investigating elevated errors on the public API.","pageWide":true}'

Use the live OpenAPI 3.1 contract at /api/openapi as the authoritative request/response reference for the deployed version.

Purpose-specific integrations

• Component automation token: updates one component through /api/v1/webhook-component/:token.
• Heartbeat token: records expected job activity through /api/v1/heartbeat/:token.
• Embed: incident banner script for another site.
• Badge: compact dynamic status response.
• Public status API: page health JSON with page access rules enforced.
• Feeds: RSS/Atom for public pages or revocable signed access.

Signed outbound webhooks

Register and test an HTTPS endpoint, copy its secret once, and validate the HMAC signature against the exact raw request body. Reject invalid timestamps/signatures, process event IDs idempotently, return success promptly, and move slow work to the receiver's queue. Rotate secrets after exposure.

Manage human identity and session risk

Create an organization user

1. Open Platform administration → User management → Teams, choose Add a team member, and enter name, user ID, email, role, and optional page scope.
2. For a new local identity, set a temporary password through the protected workflow. The user must change it at first sign-in.
3. For an existing identity, add the organization membership without replacing its current authentication method.
4. Review access after role changes, team transfers, and incident rotations. Remove or revoke access immediately when no longer needed.

Security menu

• Set up authenticator-app MFA (up to two devices), save the recovery codes, and see Multi-factor authentication below.
• Review active sessions and revoke unknown or stale sessions.
• Change passwords through the authenticated flow; relevant sessions are revoked.
• Configure OIDC or SAML using the callback/metadata values shown by SignalHub.
• Test identity connections before enforcing them.
• Create and rotate SCIM bearer tokens; test create, update, group mapping, disable, and delete behavior.

Multi-factor authentication

Authenticator-app codes (Google Authenticator, Microsoft Authenticator, Authy, 1Password and similar) protect sign-in. There is one installation-wide switch, off by default, and public status pages are never affected.

1. Turn it on. An Admin opens Platform administration → Configuration → Runtime → Sign-in policy, switches on Require authenticator codes, saves the change and presses Keep within two minutes. Create a second Admin first. Turning it on signs out every other session.
2. Enroll. After the password, people without a device are taken straight to setup: scan the QR code (or type the setup key), enter the six-digit code, then save the ten one-time recovery codes and tick I've saved these. A setup that is not confirmed within 10 minutes is discarded.
3. Sign in. Step one is the password, step two the code. Trust this device for 30 days skips the code in that browser. Five wrong codes lock attempts for 15 minutes.
4. Manage devices. Open Security (the shield in the sidebar footer, or Platform administration → Security for Admins): rename a device, add a second one (confirm with a code from the first), delete one (needs a fresh code and a second device remaining), or regenerate recovery codes. You always keep at least one device and never more than two.
5. Lost a phone. Use a recovery code, or choose Can't access your device? then I lost my device. An Admin reviews the request under Platform administration → Security → MFA requests and approves with their own fresh code. Approval deletes all devices and codes, signs the person out everywhere and requires a new enrollment at next sign-in.

Operate all organizations from the unified Admin console

Admins see the Platform group and use paths under /organization/platform. These controls have installation-wide impact and require an explicit operational reason where the workflow requests one.

Organization lifecycle

Suspension is reversible; purge is not. Before purge, confirm the organization slug, business approval, legal/retention requirements, exports, backups, and reason. Monitor the queued job and tombstone evidence to completion.

How customers and employees use a status page

• The page header communicates overall status. Service groups explain which capabilities are affected.
• Active incidents and maintenance show the latest public state and affected services.
• History contains resolved incidents, completed maintenance, and available postmortems.
• Metrics show published numeric history such as response time or uptime.
• Visitors subscribe by requesting and entering a one-time verification code, for all services or only chosen ones, and email subscribers receive a confirmation. Every message links to a preferences page where they can change services or unsubscribe; mail clients also offer one-click unsubscribe.
• RSS and Atom support feed readers. Protected pages may require a revocable signed feed URL.
• Private and audience pages show an access challenge and only reveal content allowed by policy.

Operators should test visitor workflows without an Admin session and with assistive/mobile layouts before launch.

Service groups, history and subscriptions

New status pages default to collapsed groups with an average uptime summary made of small solid daily circles. Choose expanded groups during creation, or change Appearance → Layout → Default service group view later and publish. The percentage excludes unobserved time; circle color reflects the worst observed service status that day. Mobile summaries show the most recent 30 circles.

Past incidents and past maintenance each show at most 10 items with their own history link below. Both previews and full history default to the last 90 calendar days. Change Appearance → Layout → History window to 30, 60, 90, 180 or 365 days, then publish. Incident details display the postmortem directly. Public metric charts start at 90 days and remember a visitor's selection.

Subscribe appears only when public signup is enabled globally and for the page, and at least one email/SMS provider is configured. Only usable channels are offered. A ready worker is required to send verification codes. Disabling signup does not remove existing subscribers.

Retention and displayed history

Storage defaults are 90 days for monitor checks and analytics/metric points, and 365 days for notification logs/finished delivery jobs and closed service status intervals. Platform defaults and organization overrides are applied by hourly worker cleanup. Incident records and timelines remain stored; active intervals and unfinished deliveries are preserved. Public display windows are configured separately and cannot recreate expired data. See the public pages and data lifecycle guide for exact behavior and sample-data commands.

Repeatable checks for a dependable status service

Each operator shift

• Review dashboard, active incidents, upcoming maintenance, worker readiness, queue depth, and dead letters.
• Confirm external monitoring can reach public pages.
• Handoff open communication commitments and next-update times.

Weekly

• Review failed monitors, noisy thresholds, delivery retries, certificate warnings, stale API keys, and audit anomalies (including repeated MFA_LOGIN_FAILED and MFA_LOCKED events).
• Confirm backups completed and asset protection is healthy.
• Review scheduled maintenance and its customer-facing communications for accuracy.

Monthly

• Review users, roles, page scopes, sessions, API keys, webhook endpoints, and identity mappings.
• Review MFA: people without a device, locked-out accounts and any Overdue removal requests (Platform administration → Security → MFA requests).
• Patch the base image and dependencies through the organization's release process.
• Verify audit chains and SIEM delivery.

Quarterly

• Restore PostgreSQL and assets into an isolated environment.
• Test Admin recovery, MFA recovery codes, SSO failover, and SCIM deprovisioning.
• Exercise a test incident, maintenance window, subscriber delivery, webhook verification, and key rotation plan.

Safe upgrade sequence

1. Review release notes, environment template, chart values, migrations, and dependency findings.
2. Create and verify a database and asset backup.
3. Build/pull the reviewed immutable image; run preflight and migration check.
4. Run the migration once, then roll workers and web replicas according to the deployment guide.
5. Validate readiness, migration state, login, public pages, monitors, queues, and delivery.

Start with the failing boundary

Use request IDs to correlate web, worker, provider, and audit events. Redact tokens, passwords, subscriber contacts, and encrypted material before sharing diagnostics.

SignalHub terms

Organization

A tenant boundary containing memberships, pages, incidents, monitors, subscribers, integrations, and audit data.

Status page

A visitor-facing service-health experience identified by its slug.

Hub

A parent directory of status pages for a portfolio, business unit, region, or brand.

Service / component

A customer-understandable capability whose effective health may come from manual state, incidents, maintenance, and monitors.

Incident

An unplanned service-impact record with status, severity/impact, affected services, updates, resolution, and optional postmortem.

Maintenance

A planned service window with scheduled lifecycle and affected services.

Monitor

A worker-executed availability check with failure and recovery thresholds.

Metric

A numeric time series published as a chart.

Subscriber

A verified contact that follows a status page through an enabled channel.

Destination

A tested team channel or signed webhook endpoint receiving status events.

Worker

The background runtime for checks, notifications, exports, audit delivery, retention, maintenance transitions, and lifecycle jobs.

Authenticator device

A phone app registered for one person's codes. At most two, never fewer than one once enrolled.

Recovery code

A one-time backup code for signing in without the app. Shown once and stored only as a keyed hash.

Trusted device

A browser that skips the code for 30 days. Revoked automatically whenever a device is added or removed.

MFA request

A request to remove all of a person's devices. Another Admin approves it, which forces enrollment at the next sign-in.

Break-glass

An audited emergency route for the only Admin to approve their own MFA request.

Installation administration

Admin-only cross-organization controls under /organization/platform.