Self-Hosting Guide

Initial installation and setup

Refer the Getting Started Guide guide for initial installation and setup.

Overview

SimpleNS uses a split architecture that separates application services from infrastructure services, allowing flexible deployment across single or distributed systems.

Customizing Infrastructure

The @simplens/onboard cli tool lets you to choose which infrastructure services to deploy with Docker. This gives you flexibility to use managed cloud services for some components while self-hosting others.

Selective Infrastructure Services

During onboarding, you can select which services to deploy:

Using Managed/External Services

For any service you choose not to deploy via Docker, you'll be prompted to provide connection URLs:

Plugin Configuration

The simplens.config.yaml file controls which notification providers are available and how they behave.

You can easily add a plugin in the simplens.config.yaml using the @simplens/config-gen cli tool. Refer the Plugin Installation Guide

Adding Providers

Each provider connects to an external notification service:

providers:
  - package: "@simplens/nodemailer-gmail"
    id: email-primary
    credentials:
      EMAIL_USER: ${EMAIL_USER}
      EMAIL_PASS: ${EMAIL_PASS}
    options:
      priority: 2  # Higher = preferred
      rateLimit:
        maxTokens: 500
        refillRate: 500
        refillInterval: day

  - package: "@simplens/resend"
    id: email-backup
    credentials:
      RESEND_API_KEY: ${RESEND_API_KEY}
      FROM_EMAIL: ${FROM_EMAIL}
    options:
      priority: 1  # Lower priority, used as fallback
      rateLimit:
        maxTokens: 1000
        refillRate: 100
        refillInterval: hour

channels:
  email:
    default: email-primary

Provider Options

Channel Configuration

Map channels to their default providers:

channels:
  email:
    default: email-primary
  sms:
    default: twilio-main
  push:
    default: firebase-prod

Scaling with Kafka Partitions

SimpleNS uses Kafka topic partitions to enable horizontal scaling of workers. The partition count is set at initial startup via environment variables.

Partition Environment Variables

Scaling Workers

To scale a worker, increase its corresponding partition count before first startup, then deploy multiple instances:

# Scale notification processor for email channel
EMAIL_PARTITION=4

# Scale worker for status updates
NOTIFICATION_STATUS_PARTITION=3

# Scale delayed processor
DELAYED_PARTITION=2

# Deploy multiple instances
docker-compose up -d --scale notification_processor=4
docker-compose up -d --scale worker=3
docker-compose up -d --scale delayed_processor=2

For detailed configuration of all environment variables, see the Configuration Reference.

Deployment Configurations

SimpleNS is designed to scale from a single Raspberry Pi to a multi-node Kubernetes cluster. How you deploy depends on your expected volume and whether you want to manage stateful databases yourself.

Hardware Requirements

Choose Your Setup

# Ensure MONGO, KAFKA, and REDIS point to your local docker networks
MONGO_URI=mongodb://host.docker.internal:27017/simplens?replicaSet=rs0
BROKERS=host.docker.internal:9092
REDIS_URL=redis://host.docker.internal:6379
LOKI_URL=http://host.docker.internal:3100

# Step 1: Start Infrastructure (DBs, Queues)
docker-compose -f docker-compose.infra.yaml up -d

# Step 2: Start Application Services
docker-compose up -d

# MongoDB Atlas
MONGO_URI=mongodb+srv://user:pass@cluster.mongodb.net/simplens?retryWrites=true

# Confluent Cloud Kafka / AWS MSK
BROKERS=kafka-broker.cloud-provider.com:9092

# Redis Cloud / AWS ElastiCache
REDIS_URL=redis://user:pass@redis.cloud-provider.com:6379

# Only start application services
docker-compose up -d

Application Services

The docker-compose.yaml uses pre-built images from GitHub Container Registry:

Infrastructure Services

The docker-compose.infra.yaml provides self-hosted infrastructure:

Port Reference

Config Generator CLI

The @simplens/config-gen CLI generates simplens.config.yaml from plugin manifests.

Commands

# Generate config for single plugin
npx @simplens/config-gen generate @simplens/mock

# Generate config for multiple plugins
npx @simplens/config-gen gen @simplens/nodemailer-gmail @simplens/mock

# Add plugin to existing config
npx @simplens/config-gen gen @simplens/nodemailer-gmail -c simplens.config.yaml

# Custom output path
npx @simplens/config-gen gen @simplens/mock -o custom.yaml

# Print to stdout
npx @simplens/config-gen gen @simplens/mock --stdout

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

# List community plugins
npx @simplens/config-gen list --community

Security Considerations

1. ✅ Generate strong NS_API_KEY and AUTH_SECRET values
2. ✅ Set a secure ADMIN_PASSWORD
3. ✅ Configure firewall rules to restrict infrastructure ports
4. ✅ Set up SSL/TLS for API and dashboard
5. ✅ Configure MongoDB authentication
6. ✅ Set up backup strategy for MongoDB
7. ✅ Review and limit exposed ports

Troubleshooting

Services can't connect to infrastructure

• INFRA_HOST: Ensure it matches the infrastructure machine's accessible IP
• Firewall: Check ports 27017, 9092, 6379, 3100 are open
• Network: Verify machines can ping each other

MongoDB replica set issues

# Reset and reinitialize
docker-compose -f docker-compose.infra.yaml down -v
docker-compose -f docker-compose.infra.yaml up -d
# Wait 60 seconds for auto-initialization

Plugin configuration not loading

# Verify config file exists
ls -la simplens.config.yaml

# Regenerate if needed
npx @simplens/config-gen generate @simplens/mock --stdout

# Set required environment variables in .env