Skip to main content

Configuration & Environment Variables

Complete reference for configuring Noxys through environment variables, config files, and tuning.

Configuration Methods​

Noxys reads configuration in this priority order:

  1. Environment variables (highest priority)
  2. .env file in the working directory
  3. Config file at /etc/noxys/config.yaml (optional)
  4. Default values (lowest priority)

Core Settings​

NOXYS_ENV​

Environment mode.

NOXYS_ENV=production  # production, staging, development

Effects:

  • production: No debug logs, strict TLS validation
  • staging: Warning-level logs, optional TLS
  • development: Verbose logs, self-signed certs allowed

NOXYS_PORT​

API server listening port.

NOXYS_PORT=8080

Default: 8080. Can be any available port. Use port 443 only if running as root or behind a reverse proxy.

NOXYS_JWT_SECRET​

Secret key for signing JWT tokens. Critical for security.

NOXYS_JWT_SECRET=$(openssl rand -base64 32)

Requirements:

  • Minimum 32 bytes
  • Random and unique per deployment
  • Rotate every 90 days (invalidates existing tokens)
  • Store securely (not in source control)

Database Configuration​

NOXYS_DB_URL​

PostgreSQL connection string.

NOXYS_DB_URL=postgres://username:password@host:port/database

# Examples
NOXYS_DB_URL=postgres://noxys:password@localhost:5432/noxys  # Local
NOXYS_DB_URL=postgres://noxys:pwd@postgres.internal:5432/noxys  # Internal network
NOXYS_DB_URL=postgres://noxys:pwd@db.aws.amazon.com:5432/noxys  # AWS RDS

PostgreSQL Auth Variables​

When using Docker Compose, these configure the PostgreSQL container:

POSTGRES_USER=noxys
POSTGRES_PASSWORD=secure-password-here
POSTGRES_DB=noxys

Database Connection Pooling​

Configure connection limits (optional):

NOXYS_DB_MAX_CONNECTIONS=20
NOXYS_DB_MIN_CONNECTIONS=5
NOXYS_DB_TIMEOUT=30s

Default: 10 max, 2 min, 30s timeout.

Database SSL/TLS​

For cloud-hosted databases:

NOXYS_DB_SSL_MODE=require  # require, disable, allow, prefer
NOXYS_DB_SSL_CERT=/path/to/rds-ca-2019-root.pem

Cache & Session Configuration​

NOXYS_REDIS_URL​

Redis connection for caching and sessions.

NOXYS_REDIS_URL=redis://host:port/database

# Examples
NOXYS_REDIS_URL=redis://redis:6379/0  # Local
NOXYS_REDIS_URL=redis://redis.internal:6379/0  # Internal
NOXYS_REDIS_URL=redis://:password@redis.aws.amazon.com:6379/0  # AWS with auth

Redis Configuration​

NOXYS_REDIS_TTL=3600  # Session timeout (seconds)
NOXYS_REDIS_MAX_IDLE=30  # Max idle connections

Message Queue Configuration​

NOXYS_NATS_URL​

NATS JetStream URL for event streaming.

NOXYS_NATS_URL=nats://host:port

# Examples
NOXYS_NATS_URL=nats://nats:4222  # Local
NOXYS_NATS_URL=nats://nats.internal:4222  # Internal

NATS Cluster​

For HA, use multiple servers:

NOXYS_NATS_URL=nats://nats1:4222,nats2:4222,nats3:4222

Security Configuration​

TLS/HTTPS​

# Certificate paths (PEM format)
NOXYS_TLS_CERT_PATH=/etc/noxys/tls/cert.pem
NOXYS_TLS_KEY_PATH=/etc/noxys/tls/key.pem

# Require client certificates (mTLS, optional)
NOXYS_TLS_CLIENT_CA=/etc/noxys/tls/client-ca.pem

# TLS version (default: 1.2)
NOXYS_TLS_MIN_VERSION=1.2

CORS (Cross-Origin Resource Sharing)​

# Allowed origins for browser requests (comma-separated)
NOXYS_CORS_ALLOWED_ORIGINS=https://noxys.company.com,https://admin.company.com

# Allow credentials
NOXYS_CORS_ALLOW_CREDENTIALS=true

# Allowed methods
NOXYS_CORS_ALLOWED_METHODS=GET,POST,PUT,DELETE,OPTIONS

# Allowed headers
NOXYS_CORS_ALLOWED_HEADERS=Content-Type,Authorization

Domain Whitelist​

# Domains allowed to use the extension (comma-separated)
NOXYS_ALLOWED_DOMAINS=company.com,subsidiary.com,partner.com

# Wildcard allowed
NOXYS_ALLOWED_DOMAINS=*.company.com

Rate Limiting​

# Requests per second per IP
NOXYS_RATE_LIMIT_RPS=100

# Burst capacity
NOXYS_RATE_LIMIT_BURST=200

# Cache API keys (disable for strict per-request validation)
NOXYS_RATE_LIMIT_CACHE_TTL=60

Logging & Observability​

Log Level​

NOXYS_LOG_LEVEL=info  # debug, info, warn, error

# Log format
NOXYS_LOG_FORMAT=json  # json or text

OpenTelemetry​

OTEL_ENABLED=true

# OTLP exporter
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Service name
OTEL_SERVICE_NAME=noxys-api

# Sampling rate (0-1)
OTEL_TRACES_SAMPLER_ARG=0.1  # Sample 10% of traces

Metrics​

# Prometheus metrics endpoint
NOXYS_METRICS_ENABLED=true
NOXYS_METRICS_PORT=9090

# Metrics path
NOXYS_METRICS_PATH=/metrics

Email Configuration​

SendGrid​

NOXYS_SENDGRID_API_KEY=SG.xxxx...
NOXYS_SENDGRID_FROM=noreply@noxys.eu
NOXYS_SENDGRID_FROM_NAME="Noxys Platform"

SMTP (Alternative)​

NOXYS_SMTP_HOST=smtp.company.com
NOXYS_SMTP_PORT=587
NOXYS_SMTP_USER=noxys@company.com
NOXYS_SMTP_PASSWORD=password
NOXYS_SMTP_FROM=noxys@company.com
NOXYS_SMTP_TLS=true

Integrations​

Slack Webhook​

NOXYS_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
NOXYS_SLACK_CHANNEL=#security-alerts
NOXYS_SLACK_USERNAME=Noxys Bot

Webhook Alerts​

# Send alerts to webhook endpoint
NOXYS_WEBHOOK_ENABLED=true
NOXYS_WEBHOOK_URL=https://siem.company.com/alerts
NOXYS_WEBHOOK_TIMEOUT=10s
NOXYS_WEBHOOK_RETRIES=3

Stripe (SaaS only)​

NOXYS_STRIPE_API_KEY=sk_live_xxxx...
NOXYS_STRIPE_WEBHOOK_SECRET=whsec_...

Single Sign-On​

SSO Enable​

NOXYS_SSO_ENABLED=true

SAML 2.0​

NOXYS_SAML_ENABLED=true
NOXYS_SAML_ENTITY_ID=https://noxys.company.com
NOXYS_SAML_SSO_URL=https://idp.company.com/saml/sso
NOXYS_SAML_CERTIFICATE_PATH=/etc/noxys/saml/cert.pem
NOXYS_SAML_PRIVATE_KEY_PATH=/etc/noxys/saml/key.pem

LDAP​

NOXYS_LDAP_ENABLED=true
NOXYS_LDAP_HOST=ldap.company.com
NOXYS_LDAP_PORT=389
NOXYS_LDAP_BIND_DN=cn=admin,dc=company,dc=com
NOXYS_LDAP_BIND_PASSWORD=password
NOXYS_LDAP_BASE_DN=dc=company,dc=com
NOXYS_LDAP_USER_FILTER=(uid=%s)
NOXYS_LDAP_USE_TLS=true

Microsoft Entra ID (Azure AD)​

NOXYS_OIDC_ENABLED=true
NOXYS_OIDC_PROVIDER=https://login.microsoftonline.com/common/v2.0
NOXYS_OIDC_CLIENT_ID=your-client-id
NOXYS_OIDC_CLIENT_SECRET=your-client-secret
NOXYS_OIDC_REDIRECT_URL=https://noxys.company.com/auth/oidc/callback

PII Detection Configuration​

Classification Tiers​

# Enable Tier 1 (regex, always on)
NOXYS_CLASSIFICATION_TIER1_ENABLED=true

# Enable Tier 2 (server-side Presidio)
NOXYS_CLASSIFICATION_TIER2_ENABLED=true

# Enable Tier 3 (semantic SLM, optional)
NOXYS_CLASSIFICATION_TIER3_ENABLED=false
NOXYS_CLASSIFICATION_TIER3_MODEL=mistral-7b
NOXYS_CLASSIFICATION_TIER3_ENDPOINT=http://ollama:11434

Classification Sensitivity​

# Confidence threshold (0-1), higher = fewer false positives
NOXYS_CLASSIFICATION_CONFIDENCE_THRESHOLD=0.7

# Include low-confidence matches
NOXYS_CLASSIFICATION_INCLUDE_LOW_CONFIDENCE=false

Data Retention​

Interaction Retention​

# How long to keep interaction records (days)
NOXYS_INTERACTION_RETENTION=90

# Archive old interactions to cold storage (optional)
NOXYS_INTERACTION_ARCHIVE_ENABLED=true
NOXYS_INTERACTION_ARCHIVE_AFTER_DAYS=30
NOXYS_INTERACTION_ARCHIVE_LOCATION=s3://bucket/archive

Audit Log Retention​

# How long to keep audit logs (days)
NOXYS_AUDIT_LOG_RETENTION=365

# Immutable storage (WORM)
NOXYS_AUDIT_LOG_IMMUTABLE=true

Policy Configuration​

Policy Evaluation​

# Cache policy decisions (seconds)
NOXYS_POLICY_CACHE_TTL=60

# Timeout for policy evaluation (milliseconds)
NOXYS_POLICY_EVALUATION_TIMEOUT=5000

# Enable policy versioning
NOXYS_POLICY_VERSIONING_ENABLED=true

Performance Tuning​

Connection Pooling​

NOXYS_DB_MAX_CONNECTIONS=20
NOXYS_DB_MIN_CONNECTIONS=5
NOXYS_REDIS_MAX_IDLE=30
NOXYS_REDIS_MAX_ACTIVE=50

Caching​

# Cache TTL for classifications
NOXYS_CLASSIFICATION_CACHE_TTL=3600

# Cache interactions
NOXYS_INTERACTION_CACHE_TTL=300

# Cache size (MB)
NOXYS_CACHE_MAX_SIZE=500

Request Processing​

# Max request size (bytes)
NOXYS_MAX_REQUEST_SIZE=10485760  # 10 MB

# Read timeout
NOXYS_READ_TIMEOUT=30s

# Write timeout
NOXYS_WRITE_TIMEOUT=30s

# Idle timeout
NOXYS_IDLE_TIMEOUT=90s

Compliance & Privacy​

EU AI Act​

# Enable EU AI Act compliance features
NOXYS_EU_AI_ACT_ENABLED=true

# Compliance mode (strict adherence to regulations)
NOXYS_COMPLIANCE_MODE=strict

GDPR​

# Data residency (EU only)
NOXYS_DATA_RESIDENCY=eu

# Right to erasure enforcement
NOXYS_RIGHT_TO_ERASURE_ENABLED=true

# Data minimization (don't store unnecessary data)
NOXYS_DATA_MINIMIZATION_ENABLED=true

Encryption​

# Encrypt data at rest (application-level)
NOXYS_ENCRYPTION_AT_REST_ENABLED=true
NOXYS_ENCRYPTION_KEY_PATH=/etc/noxys/encryption/key

# Hash algorithm
NOXYS_HASH_ALGORITHM=sha256

Backup Configuration​

Automated Backups​

# Enable automated backups
NOXYS_BACKUP_ENABLED=true

# Backup schedule (cron format)
NOXYS_BACKUP_SCHEDULE="0 2 * * *"  # 2 AM daily

# Backup location
NOXYS_BACKUP_LOCATION=/var/backups/noxys

# Retention policy (days)
NOXYS_BACKUP_RETENTION=30

# S3 backup (optional)
NOXYS_BACKUP_S3_ENABLED=false
NOXYS_BACKUP_S3_BUCKET=noxys-backups
NOXYS_BACKUP_S3_REGION=eu-west-1
NOXYS_BACKUP_S3_ACCESS_KEY=AKIA...
NOXYS_BACKUP_S3_SECRET_KEY=...

Configuration File Example​

Instead of environment variables, you can use a YAML config file:

# /etc/noxys/config.yaml
noxys:
  env: production
  port: 8080
  jwtSecret: "generated-random-secret"

database:
  url: "postgres://noxys:password@postgres:5432/noxys"
  maxConnections: 20
  minConnections: 5

redis:
  url: "redis://redis:6379/0"
  ttl: 3600

nats:
  url: "nats://nats:4222"

security:
  tlsCertPath: "/etc/noxys/tls/cert.pem"
  tlsKeyPath: "/etc/noxys/tls/key.pem"
  corsAllowedOrigins:
    - "https://noxys.company.com"
  allowedDomains:
    - "company.com"

logging:
  level: info
  format: json

observability:
  otel:
    enabled: true
    endpoint: "http://localhost:4317"
  metrics:
    enabled: true
    port: 9090

sso:
  enabled: true
  saml:
    enabled: true
    entityId: "https://noxys.company.com"
    ssoUrl: "https://idp.company.com/saml/sso"

compliance:
  euAiActEnabled: true
  dataResidency: "eu"
  encryptionAtRest: true

Load with:

NOXYS_CONFIG_PATH=/etc/noxys/config.yaml noxys start

Validation​

Check Configuration​

# Dry-run mode (validates config without starting)
NOXYS_DRY_RUN=true noxys start

# Output resolved configuration
noxys config show

Environment Variables Checklist​

# Required
NOXYS_ENV=production
NOXYS_JWT_SECRET=<32+ bytes>
NOXYS_DB_URL=postgres://...
NOXYS_REDIS_URL=redis://...
NOXYS_NATS_URL=nats://...

# Recommended for production
NOXYS_TLS_CERT_PATH=/path/to/cert.pem
NOXYS_TLS_KEY_PATH=/path/to/key.pem
NOXYS_CORS_ALLOWED_ORIGINS=https://noxys.company.com
NOXYS_ALLOWED_DOMAINS=company.com

# Optional (integrations)
OTEL_ENABLED=true
NOXYS_SLACK_WEBHOOK_URL=https://...

Next Steps​

Questions? Email support@noxys.eu