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

Quick Start

Get SimpleNS running on your machine (local or remote) in under a minute with a single command.

Run this command in your terminal:

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

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

Run this command in PowerShell (as Administrator):

irm https://simplens.vercel.app/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 automatically:

Pull the required Docker images
Configure your environment
Set up the plugin configuration
Start all SimpleNS services

Verify Installation

Once the installation completes, check that the API server is running:

curl http://localhost:3000/health

Expected response:

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

Send Your First Notification

Using the dashboard (recommended for first-time users):

Open http://localhost:3002
Login with:
- Username: admin
- Password: <your-password-from-env>
Navigate to Send
Select channel: Select available channel and provider (channels and providers can be configured in simplens.config.yaml file)
Fill in the required (*) fields
Click "Send Notification"

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!"
      }
    }
  }'

Expected response (202 Accepted):

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

As each provider's recipient and content schemas can vary, you can get the schema from Payload Studio section in the admin dashboard. See the Admin Dashboard Guide

Check Notification Status

View your notification in the dashboard:

Go to Events page
Search for your notification by ID
Check status: pending → processing → delivered

Next Steps

Congratulations! 🎉

You've successfully sent your first notification through SimpleNS.

Add More Plugins

# Add Gmail email provider
npx @simplens/config-gen generate @simplens/nodemailer-gmail -c simplens.config.yaml

# List available plugins
npx @simplens/config-gen list --official

Build Your Own Plugin

Use the CLI tool to scaffold a new plugin:

npx @simplens/create-simplens-plugin

See Plugin Development Guide for details.

Troubleshooting

Services won't start

Check logs:

docker compose -f docker-compose.dev.yaml logs <service-name>

Common issues

Ports already in use (3000, 3002, 27017, 9092, 6379)
MongoDB replica set initialization - wait 60s and check again
Missing .env file

Notification stuck in pending

Possible causes:

Worker not running: docker compose -f docker-compose.dev.yaml ps worker
Processor not running: docker compose -f docker-compose.dev.yaml ps notification_processor
Kafka connection issues: Check Kafka UI at http://localhost:8080

Plugin not loading

Check:

Config exists: cat simplens.config.yaml
Environment variables set in .env
Restart processor: docker compose -f docker-compose.dev.yaml restart notification_processor

For more issues, see Troubleshooting Guide.

Accessing Services

Once running, you can access:

API Server

Notification API - Port 3000

Admin Dashboard

Monitoring & management - Port 3002

Grafana

Log visualization - Port 3001

Kafka UI

Kafka topic monitoring - Port 8080

Production Deployment

For production environments, see the Self-Hosting Guide which covers:

Split Docker Compose files for flexibility
Distributed deployments across multiple hosts
Cloud infrastructure integration
Security hardening

Getting Started

API Server

Admin Dashboard

Grafana

Kafka UI

On this page