Local Development

Overview

SimpleNS includes a pre-configured Dev Container setup that provides a complete development environment with all required tools, extensions, and infrastructure services. This allows you to start contributing or customizing SimpleNS without manual environment setup.

Prerequisites

Before you begin, ensure you have the following installed:

• Docker Desktop (Windows/Mac) or Docker Engine (Linux)
• VS Code with the Dev Containers extension
• Git for cloning the repository

Getting Started

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

# Automatically executed on container creation:
npm install && cd dashboard && npm install

# Automatically executed on container start:
docker compose -f docker-compose.infra.yaml up -d

# Check Node.js
node --version  # Should show Node.js 18+

# Check Docker-in-Docker
docker ps  # Should list running infrastructure containers

# Verify infrastructure services
docker compose -f docker-compose.infra.yaml ps

Dev Container Configuration

The .devcontainer/devcontainer.json configures the development environment:

Base Image

{
  "name": "SimpleNS Devcontainer",
  "image": "mcr.microsoft.com/devcontainers/typescript-node"
}

Uses Microsoft's TypeScript/Node.js development container image which includes:

• Node.js LTS
• TypeScript
• Common development utilities

Docker-in-Docker

{
  "features": {
    "ghcr.io/devcontainers/features/docker-in-docker:2": {
      "moby": false
    }
  }
}

VS Code Extensions

The following extensions are automatically installed:

Environment Variables

{
  "remoteEnv": {
    "NODE_ENV": "development",
    "INFRA_HOST": "localhost"
  }
}

Infrastructure Services

The Dev Container automatically starts infrastructure services via docker-compose.infra.yaml:

Managing Infrastructure

# View running services
docker compose -f docker-compose.infra.yaml ps

# View logs
docker compose -f docker-compose.infra.yaml logs -f

# Stop services
docker compose -f docker-compose.infra.yaml down

# Restart services
docker compose -f docker-compose.infra.yaml restart

Running the Application

Once the Dev Container is ready, start the application services:

# Copy example environment file
cp .env.example .env

# Edit the .env file with your settings

# Generate config for mock plugin (for testing)
npx @simplens/config-gen generate @simplens/mock

# Terminal 1: API Server
npm run dev

# Terminal 2: Background Worker (status updates processing)
npm run worker:dev

# Terminal 3: Notification Processor (plugin-based delivery)
npm run processor:dev

# Terminal 4: Delayed Processor (scheduled notifications)
npm run delayed-processor:dev

# Terminal 5: Recovery Service (stuck notification detection)
npm run recovery:dev

# Terminal 6: Dashboard (in dashboard directory)
cd dashboard && npm run dev

docker compose -f docker-compose.dev.yaml up -d

Running Tests

The Dev Container includes the Vitest extension for running tests:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Troubleshooting

Container fails to start

Check Docker Desktop is running:

• Ensure Docker Desktop (or Docker Engine) is running before opening VS Code

Rebuild the container:

1. Press Ctrl+Shift+P → "Dev Containers: Rebuild Container"
2. Wait for the rebuild to complete

Infrastructure services not running

Manually start services:

docker compose -f docker-compose.infra.yaml up -d

Check Docker-in-Docker:

docker ps
# Should show infrastructure containers

MongoDB connection issues

Wait for replica set initialization: MongoDB replica set initialization can take up to 30 seconds. Check the health status:

docker compose -f docker-compose.infra.yaml ps mongo
# Should show 'healthy' status

Extension not working

Reload VS Code:

1. Press Ctrl+Shift+P → "Developer: Reload Window"
2. Wait for extensions to activate