Skip to main content

nostream

Production-ready Nostr relay. TypeScript implementation with PostgreSQL backend.

Overview​

nostream is a Nostr relay written in TypeScript, designed for production deployments. It uses PostgreSQL for storage, providing a robust and scalable solution for running your own relay.

Key Features​

Production Architecture​

┌─────────────────────────────────────────────────────────┐
│                    nostream                              │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌─────────────────────────────────────────────────────┐│
│  │              WebSocket Server                       ││
│  │         (handles client connections)                ││
│  └─────────────────────────────────────────────────────┘│
│                         │                                │
│                         ▼                                │
│  ┌─────────────────────────────────────────────────────┐│
│  │              Event Processing                       ││
│  │    (validation, rate limiting, filtering)          ││
│  └─────────────────────────────────────────────────────┘│
│                         │                                │
│                         ▼                                │
│  ┌─────────────────────────────────────────────────────┐│
│  │               PostgreSQL                            ││
│  │       (persistent event storage)                    ││
│  └─────────────────────────────────────────────────────┘│
│                                                          │
└─────────────────────────────────────────────────────────┘

PostgreSQL Storage​

BenefitDescription
ReliabilityACID compliance
ScalabilityHandles large datasets
QueryingComplex filter support
BackupsStandard PostgreSQL tools

NIP Support​

NIPFeature
NIP-01Basic protocol
NIP-02Contact lists
NIP-04Encrypted DMs
NIP-09Event deletion
NIP-11Relay information
NIP-12Generic tag queries
NIP-15End of stored events
NIP-16Event treatment
NIP-20Command results
NIP-22Event created_at limits
NIP-26Delegated events
NIP-28Public chat
NIP-33Parameterized replaceable
NIP-40Expiration timestamp
NIP-42Authentication

Payment Integration​

Monetize your relay:

payments:
  enabled: true
  processor: lnbits
  feeSchedules:
    admission:
      - amount: 1000
        description: "1 year access"

Support for:

  • LNURL
  • Zebedee
  • LNbits
  • nodeless

Installation​

# docker-compose.yml
version: '3'
services:
  nostream:
    image: cameri/nostream:latest
    depends_on:
      - postgres
      - redis
    ports:
      - "8008:8008"
    environment:
      RELAY_PORT: 8008
      DB_HOST: postgres
      DB_PORT: 5432
      DB_NAME: nostream
      DB_USER: nostream
      DB_PASSWORD: nostream
      REDIS_HOST: redis

  postgres:
    image: postgres:14-alpine
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: nostream
      POSTGRES_PASSWORD: nostream
      POSTGRES_DB: nostream

  redis:
    image: redis:7-alpine

From Source​

git clone https://github.com/Cameri/nostream.git
cd nostream

# Install dependencies
npm install

# Configure
cp .env.example .env
# Edit .env with your settings

# Run migrations
npm run db:migrate

# Start
npm start

Configuration​

Basic Settings​

# settings.yaml

info:
  relay_url: wss://relay.example.com
  name: My Relay
  description: A nostream relay
  pubkey: <your-npub>
  contact: admin@example.com

limits:
  event:
    eventId:
      minLeadingZeroBits: 0
    kind:
      whitelist: []
      blacklist: []
    pubkey:
      minLeadingZeroBits: 0
      whitelist: []
      blacklist: []
    createdAt:
      maxPositiveDelta: 900
      maxNegativeDelta: 0

  message:
    rateLimits:
      - period: 60000
        rate: 60

  client:
    subscription:
      maxSubscriptions: 10
      maxFilters: 10

Rate Limiting​

limits:
  message:
    rateLimits:
      - period: 60000    # 1 minute
        rate: 60         # 60 events
      - period: 3600000  # 1 hour
        rate: 1000       # 1000 events

Event Filtering​

limits:
  event:
    kind:
      whitelist: [0, 1, 3, 4, 5, 6, 7]  # Only these kinds
      # or
      blacklist: [30000]                 # Block these kinds

Comparison​

Featurenostreamstrfry
LanguageTypeScriptC++
DatabasePostgreSQLLMDB
Memory usageHigherLower
Query flexibilityHighMedium
ScalingHorizontalVertical
PaymentsBuilt-inPlugin

Operations​

Monitoring​

nostream provides metrics for:

  • Connection counts
  • Event throughput
  • Database performance
  • Error rates

Backups​

# PostgreSQL backup
pg_dump nostream > backup.sql

# Restore
psql nostream < backup.sql

Scaling​

  • Run multiple nostream instances
  • Use PostgreSQL replication
  • Load balance with nginx

See Also​