Getting Started

Get SimpleNS up and running in under a minute. This guide will walk you through setting up a local instance and sending your first notification.

Prerequisites

Before you begin, ensure you have the following installed:

Docker and Docker Compose

5-Minute Quickstart

Get SimpleNS running on your machine and send your first notification in under 5 minutes.

Step 1: Install & Start

Run this command in your terminal to start the @simplens/onboard cli tool

Run this command in your terminal:

curl -fsSL https://simplens.in/api/install/linux | bash

Works on Ubuntu, Debian, CentOS, and other Linux distros.

Run this command in PowerShell (as Administrator):

irm https://simplens.in/api/install/windows | iex

Requires PowerShell 5.1+ running as Administrator.

Quick start with npx:

npx @simplens/onboard

Or install globally:

npm i -g @simplens/onboard

Requires Node.js 18+ and npm installed.

The installer will create the following files:

docker-compose.yaml: Contains the application services
docker-compose.infra.yaml: Contains the infrastructure services like mongo, kafka, redis, loki and grafana. (These services are customizable in the @simplens/onboard tool. docker-compose.infra.yaml file is optional as it will not be created if you don't want any infra services to run. It is automatically created when SSL is enabled.)
.env: Contains the environmental variables
simplens.config.yaml: Contains the configurations for simplens plugins
nginx.conf: An optional nginx configuration file if BASE_PATH is enabled and configured in the @simplens/onboard cli tool, or when SSL is enabled
nginx.ssl.conf: Generated when SSL is enabled and services are not auto-started; this is the final HTTPS Nginx config used after certificate issuance

Step 2: Verify Health

Ensure the core API server is running and healthy:

curl http://localhost:3000/health

Expected response:

{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Step 3: Send Your First Notification

We'll use the built-in mock channel, which requires no external provider credentials, just to test the flow.

curl -X POST http://localhost:3000/api/notification \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-NS-API-KEY>" \
  -d '{
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "client_id": "55283667-1f58-467d-86a1-47f7f0e059f2",
    "channel": ["mock"],
    "recipient": {
      "user_id": "user123"
    },
    "content": {
      "mock": {
        "message": "Hello from SimpleNS!"
      }
    }
  }'

const response = await fetch('http://localhost:3000/api/notification', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <YOUR-NS-API-KEY>'
  },
  body: JSON.stringify({
    request_id: crypto.randomUUID(),
    client_id: "55283667-1f58-467d-86a1-47f7f0e059f2",
    channel: ["mock"],
    recipient: { user_id: "user123" },
    content: { mock: { message: "Hello from SimpleNS!" } }
  })
});

Expected response (202 Accepted):

{
   "message": "Notifications are being processed"
}

Step 4: Check Dashboard

Open your browser to the Admin Dashboard (default: http://localhost:3002). Login with username admin and check the Events page to search for your notification by ID.

Congratulations! 🎉

You've successfully deployed SimpleNS and sent your first notification.

Automatic HTTPS (Let's Encrypt)

@simplens/onboard can automatically configure HTTPS using Nginx + Certbot with Let's Encrypt HTTP-01 challenge.

Flags

--ssl: Enable SSL automation.
--ssl-domain <domain>: Public FQDN used for certificate issuance.
--ssl-email <email>: Email used for Let's Encrypt registration.

Domain and email are validated before setup:

Domain must be a valid public FQDN (no protocol, path, wildcard, query, or port).
Email must be a valid email format.

Mode Behavior

In interactive mode (without --full):

If --ssl is not passed, onboard asks whether to enable automatic SSL.
If enabled, onboard prompts for domain and email.
Onboard asks whether to start services immediately.

If you choose to start now, onboard performs the SSL bootstrap flow automatically:

Starts Nginx with a bootstrap nginx.conf for ACME challenge.
Requests the first certificate with Certbot webroot mode.
Switches to final SSL-enabled nginx.conf and reloads Nginx.
Starts certbot-renew for periodic renewals (12h check interval).

In --full mode:

No interactive prompts are shown.
--ssl-domain and --ssl-email are required when --ssl is set.
Missing or invalid values fail fast during CLI validation.
Services are not auto-started by design.

Onboard generates all files and prints the manual SSL runbook commands.

Prerequisites for Certificate Issuance

Before running SSL issuance, make sure:

Your domain is registered.
An A record points your domain to this machine public IP.
Ports 80 and 443 are open and reachable from the internet.

Quick Examples

Interactive SSL setup:

npx @simplens/onboard --infra --env interactive
# then enable SSL in the prompt flow

Non-interactive SSL setup (--full):

npx @simplens/onboard \
  --full \
  --infra mongo kafka redis nginx \
  --env default \
  --ssl \
  --ssl-domain app.example.com \
  --ssl-email ops@example.com

Manual SSL Runbook

When services are not auto-started (for example in --full mode), run:

# 1) Start infra services (includes nginx bootstrap config)
docker compose -f docker-compose.infra.yaml up -d

# 2) Start application services
docker compose up -d

# 3) Request certificate
docker compose -f docker-compose.infra.yaml run --rm --no-deps --entrypoint certbot certbot certonly --webroot -w /var/www/certbot --email <email> --agree-tos --no-eff-email -d <domain> --non-interactive

# 4) Swap config file
# Windows:
copy /Y nginx.ssl.conf nginx.conf
# Linux/macOS:
cp nginx.ssl.conf nginx.conf

# 5) Reload nginx
docker compose -f docker-compose.infra.yaml exec -T nginx nginx -s reload

# 6) Start renewal service
docker compose -f docker-compose.infra.yaml up -d certbot-renew

Automated compose execution in onboard attempts docker compose and falls back to docker-compose if needed. Manual instructions are printed using docker compose commands.

Troubleshooting

Common validation failure in --full mode:

npx @simplens/onboard --full --env default --ssl --ssl-domain app.example.com --ssl-email ops@example.com

If certificate issuance fails, check:

docker compose -f docker-compose.infra.yaml ps
docker compose -f docker-compose.infra.yaml logs nginx
docker compose -f docker-compose.infra.yaml run --rm --no-deps --entrypoint certbot certbot certificates

If Nginx reload fails, check:

docker compose -f docker-compose.infra.yaml exec -T nginx nginx -t

And verify cert paths in nginx.conf under:

/etc/letsencrypt/live/<domain>/fullchain.pem
/etc/letsencrypt/live/<domain>/privkey.pem