Getting Started

Get SimpleNS up and running in 5 minutes. 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
Node.js 18+ (for config generation)
OpenSSL (for generating secrets)

Quick Start

Clone the Repository

git clone https://github.com/SimpleNotificationSystem/simplens-core.git
cd simplens-core

Configure Environment

Copy the example environment file and generate secrets:

# Copy environment template
cp .env.example .env

# Generate API key
openssl rand -base64 32  # Copy this to NS_API_KEY in .env

# Generate auth secret
openssl rand -base64 32  # Copy this to AUTH_SECRET in .env

Edit .env and set at minimum:

NS_API_KEY=<generated-api-key>
AUTH_SECRET=<generated-auth-secret>
ADMIN_PASSWORD=<strong-password>

Generate Plugin Configuration

Use the config generator to create simplens.config.yaml:

# For testing (mock provider)
npx @simplens/config-gen generate @simplens/mock

Add the partition config to .env:

MOCK_PARTITION=1

For email notifications, use npx @simplens/config-gen generate @simplens/nodemailer-gmail and configure your Gmail credentials.

Start Services

# Start all services (development mode)
docker compose -f docker-compose.dev.yaml up -d

This starts:

MongoDB (database)
Kafka (message queue)
Redis (caching & delay queue)
Loki (log aggregation)
Grafana (log visualization)
API Server
Background Worker
Notification Processor
Delayed Processor
Recovery Service
Admin Dashboard

Wait for services to be healthy (about 30-60 seconds):

docker compose -f docker-compose.dev.yaml ps

Verify Installation

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: mock
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