Docker Compose Deployment

Deploy Noxys locally or in a small environment using Docker Compose in 30 minutes.

Quick Start

Development

Get Noxys running on your machine with demo data:

git clone https://github.com/noxys-io/noxys.git
cd noxys
make dev

This starts:

• PostgreSQL (port 5432)
• Redis (port 6379)
• NATS JetStream (port 4222)
• Go API (port 8080)
• React Dashboard (port 3000)

Access the dashboard at http://localhost:3000 (demo credentials in setup).

Production

For a production-like deployment with health checks and resource limits:

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Key differences from dev:

• Health checks enabled
• Resource limits configured
• No debug logging
• TLS certificate required (see HTTPS setup)
• Persistent volumes for data

Configuration

1. Clone & Setup

git clone https://github.com/noxys-io/noxys.git
cd noxys
cp .env.example .env

2. Edit .env File

Required variables:

# Environment
NOXYS_ENV=production
NOXYS_PORT=8080
NOXYS_JWT_SECRET=your-secret-key-min-32-bytes-long-here

# Database
POSTGRES_USER=noxys
POSTGRES_PASSWORD=secure-password-here
POSTGRES_DB=noxys
NOXYS_DB_URL=postgres://noxys:secure-password-here@postgres:5432/noxys

# Redis
NOXYS_REDIS_URL=redis://redis:6379/0

# NATS
NOXYS_NATS_URL=nats://nats:4222

# Security
NOXYS_CORS_ALLOWED_ORIGINS=https://noxys.company.com
NOXYS_ALLOWED_DOMAINS=company.com,subsidiary.com
NOXYS_TLS_CERT_PATH=/etc/noxys/tls/cert.pem
NOXYS_TLS_KEY_PATH=/etc/noxys/tls/key.pem

3. Add TLS Certificates

Store your certificate and key in the volume directory:

mkdir -p ./certs
cp /path/to/cert.pem ./certs/
cp /path/to/key.pem ./certs/
chmod 400 ./certs/key.pem

Update docker-compose.prod.yml to mount the certs:

services:
  proxy:
    volumes:
      - ./certs:/etc/noxys/tls:ro

Docker Compose File Structure

docker-compose.yml (Base)

version: '3.9'

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-noxys}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-noxys}
      POSTGRES_DB: ${POSTGRES_DB:-noxys}
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./scripts/init.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U noxys"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  nats:
    image: nats:latest
    ports:
      - "4222:4222"
      - "6222:6222"
      - "8222:8222"
    command: -js -sd /data
    volumes:
      - nats_data:/data
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:8222/varz"]
      interval: 10s
      timeout: 5s
      retries: 5

  api:
    image: noxys/proxy:latest
    environment:
      NOXYS_ENV: ${NOXYS_ENV:-production}
      NOXYS_PORT: 8080
      NOXYS_JWT_SECRET: ${NOXYS_JWT_SECRET}
      NOXYS_DB_URL: ${NOXYS_DB_URL}
      NOXYS_REDIS_URL: ${NOXYS_REDIS_URL}
      NOXYS_NATS_URL: ${NOXYS_NATS_URL}
      NOXYS_CORS_ALLOWED_ORIGINS: ${NOXYS_CORS_ALLOWED_ORIGINS}
      NOXYS_ALLOWED_DOMAINS: ${NOXYS_ALLOWED_DOMAINS}
    ports:
      - "${NOXYS_PORT:-8080}:8080"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
      nats:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/healthz"]
      interval: 10s
      timeout: 5s
      retries: 3

  console:
    image: noxys/console:latest
    ports:
      - "3000:3000"
    environment:
      REACT_APP_API_URL: http://localhost:8080
    depends_on:
      - api

volumes:
  postgres_data:
  redis_data:
  nats_data:

networks:
  default:
    driver: bridge

docker-compose.prod.yml (Overrides)

version: '3.9'

services:
  postgres:
    restart: always
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

  redis:
    restart: always
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M

  nats:
    restart: always
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G

  api:
    restart: always
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 4G
        reservations:
          cpus: '2'
          memory: 2G
    environment:
      NOXYS_LOG_LEVEL: info
    volumes:
      - ./certs:/etc/noxys/tls:ro

  console:
    restart: always
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

Starting Services

All Services

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Single Service

docker compose up -d api

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f api

# Last 100 lines
docker compose logs --tail=100 api

Check Status

docker compose ps

Database Setup

Automatic Initialization

On first run, PostgreSQL applies scripts/init.sql automatically (via docker-entrypoint-initdb.d).

Manual Initialization

docker compose exec postgres psql -U noxys -d noxys < scripts/init.sql

Seed Demo Data

docker compose exec postgres psql -U noxys -d noxys < scripts/dev/seed-demo.sql

Or via Makefile:

make seed

Environment Variables

Core

Variable	Default	Purpose
NOXYS_ENV	development	Environment mode (development, staging, production)
NOXYS_PORT	8080	API server port
NOXYS_JWT_SECRET	(required)	JWT signing secret (minimum 32 bytes)

Database

Variable	Default	Purpose
NOXYS_DB_URL	postgres://user:pass@localhost/noxys	PostgreSQL connection
POSTGRES_USER	noxys	PostgreSQL username
POSTGRES_PASSWORD	noxys	PostgreSQL password
POSTGRES_DB	noxys	Database name

Cache & Messaging

Variable	Default	Purpose
NOXYS_REDIS_URL	redis://localhost:6379/0	Redis connection
NOXYS_NATS_URL	nats://localhost:4222	NATS JetStream URL

Security

Variable	Default	Purpose
NOXYS_CORS_ALLOWED_ORIGINS	http://localhost:3000	CORS origins (comma-separated)
NOXYS_ALLOWED_DOMAINS	localhost	Allowed domains for extension
NOXYS_TLS_CERT_PATH	(empty)	TLS certificate (PEM)
NOXYS_TLS_KEY_PATH	(empty)	TLS private key (PEM)

Optional Features

Variable	Default	Purpose
NOXYS_SLACK_WEBHOOK_URL	(empty)	Slack integration
NOXYS_SENDGRID_API_KEY	(empty)	Email delivery
NOXYS_STRIPE_API_KEY	(empty)	Billing (SaaS only)
NOXYS_SSO_ENABLED	false	Enable SSO
OTEL_ENABLED	false	OpenTelemetry tracing
OTEL_EXPORTER_OTLP_ENDPOINT	http://localhost:4317	OTEL collector

TLS/HTTPS Setup

Option 1: Let's Encrypt (Recommended)

# Install certbot
sudo apt-get install certbot python3-certbot-nginx

# Generate certificate
sudo certbot certonly --standalone -d noxys.company.com

# Update .env
NOXYS_TLS_CERT_PATH=/etc/letsencrypt/live/noxys.company.com/fullchain.pem
NOXYS_TLS_KEY_PATH=/etc/letsencrypt/live/noxys.company.com/privkey.pem

# Restart
docker compose restart api

Option 2: Self-Signed (Development)

openssl req -x509 -newkey rsa:4096 -nodes \
  -out ./certs/cert.pem -keyout ./certs/key.pem -days 365

Option 3: Corporate CA

Place your certificate and key in ./certs/ and reference in .env.

Reverse Proxy (Nginx)

For production, use a reverse proxy to handle TLS and rate limiting:

upstream noxys_api {
    server localhost:8080;
}

upstream noxys_console {
    server localhost:3000;
}

server {
    listen 443 ssl http2;
    server_name noxys.company.com;

    ssl_certificate /etc/letsencrypt/live/noxys.company.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/noxys.company.com/privkey.pem;

    # Security headers
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Frame-Options "DENY" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    location /api/ {
        proxy_pass http://noxys_api;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location / {
        proxy_pass http://noxys_console;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

server {
    listen 80;
    server_name noxys.company.com;
    return 301 https://$server_name$request_uri;
}

Health Checks & Readiness

Noxys provides Kubernetes-compatible health endpoints:

# Liveness probe (basic responsiveness)
curl http://localhost:8080/healthz
# Returns: 200 OK

# Readiness probe (dependencies healthy)
curl http://localhost:8080/readyz
# Returns: 200 OK if DB, Redis, NATS are accessible

Backup & Restore

Automated Backup

make backup

# To S3
make backup S3=s3://my-backup-bucket/noxys

# Keep 30 days of backups
make backup KEEP=30

Manual Backup

docker compose exec postgres pg_dump -U noxys noxys | gzip > backup.sql.gz

Restore from Backup

make restore FILE=backups/noxys_backup_2026-03-20_120000.sql.gz

Stopping & Cleanup

Stop All Services

docker compose down

Stop & Remove Volumes (Full Reset)

docker compose down -v

Troubleshooting

Services Won't Start

# Check logs
docker compose logs api

# Check port conflicts
lsof -i :8080
lsof -i :5432

# Clean and restart
docker compose down -v
docker compose up -d

High Database Latency

# Check queries
docker compose exec postgres psql -U noxys -d noxys \
  -c "EXPLAIN ANALYZE SELECT * FROM interactions LIMIT 10;"

# Add missing indexes
docker compose exec postgres psql -U noxys -d noxys < scripts/indexes.sql

Out of Disk Space

# Check usage
df -h
du -sh /var/lib/docker/volumes/

# Remove old backups
rm backups/*.sql.gz

Next Steps

• Configuration Guide
• Upgrade Procedures
• Kubernetes Deployment (for larger scale)

---

Need help? Email support@noxys.eu