January 1, 2025

Configuration Guide

This guide covers all configuration options for Rox.

Environment Variables

Rox is configured entirely through environment variables. Copy .env.example to .env and customize as needed.

Database Configuration

PostgreSQL (Recommended)

DB_TYPE=postgres
DATABASE_URL=postgresql://username:password@host:5432/database

Options:

username: Database user
password: Database password
host: Database host (default: localhost)
5432: PostgreSQL port
database: Database name

MySQL

DB_TYPE=mysql
DATABASE_URL=mysql://username:password@host:3306/database

SQLite

DB_TYPE=sqlite
DATABASE_URL=sqlite://./rox.db

Cloudflare D1

DB_TYPE=d1
# D1 binding configured in wrangler.toml

Storage Configuration

Local Storage

STORAGE_TYPE=local
LOCAL_STORAGE_PATH=./uploads

Options:

LOCAL_STORAGE_PATH: Directory for uploaded files (default: ./uploads)

S3-Compatible Storage

STORAGE_TYPE=s3
S3_ENDPOINT=https://your-account.r2.cloudflarestorage.com
S3_BUCKET_NAME=rox-media
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
S3_REGION=auto
S3_PUBLIC_URL=https://media.your-domain.com

Options:

S3_ENDPOINT: S3 endpoint URL
S3_BUCKET_NAME: Bucket name
S3_ACCESS_KEY: Access key ID
S3_SECRET_KEY: Secret access key
S3_REGION: Region (use auto for Cloudflare R2)
S3_PUBLIC_URL: Public URL for media (optional)

Supported Providers:

AWS S3
Cloudflare R2
MinIO
DigitalOcean Spaces
Backblaze B2

Server Configuration

NODE_ENV=production
PORT=3000
FRONTEND_PORT=3001
FRONTEND_URL=https://your-domain.com
BACKEND_URL=https://api.your-domain.com

Options:

NODE_ENV: Environment (development or production)
PORT: Backend server port (default: 3000)
FRONTEND_PORT: Frontend server port (default: 3001)
FRONTEND_URL: Frontend public URL
BACKEND_URL: Backend public URL

Security Configuration

JWT_SECRET=your-very-secure-random-string-at-least-32-chars
SESSION_SECRET=another-secure-random-string-at-least-32-chars
COOKIE_SECURE=true
COOKIE_DOMAIN=.your-domain.com

Options:

JWT_SECRET: Secret for JWT tokens (required, min 32 chars)
SESSION_SECRET: Secret for sessions (required, min 32 chars)
COOKIE_SECURE: Use secure cookies (default: true in production)
COOKIE_DOMAIN: Cookie domain (optional)

Generate Secure Secrets:

# Using openssl
openssl rand -base64 32

# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# Using Bun
bun -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Instance Configuration

INSTANCE_NAME=Your Instance Name
INSTANCE_DESCRIPTION=A description of your instance
[email protected]
INSTANCE_ICON_URL=https://your-domain.com/icon.png
INSTANCE_BANNER_URL=https://your-domain.com/banner.png

Options:

INSTANCE_NAME: Name of your instance
INSTANCE_DESCRIPTION: Description shown on instance info
ADMIN_EMAIL: Admin contact email
INSTANCE_ICON_URL: Instance icon/logo URL
INSTANCE_BANNER_URL: Instance banner image URL

Federation Configuration

FEDERATION_ENABLED=true
FEDERATION_ALLOWLIST=
FEDERATION_BLOCKLIST=
SHARED_INBOX_ENABLED=true

Options:

FEDERATION_ENABLED: Enable ActivityPub federation (default: true)
FEDERATION_ALLOWLIST: Comma-separated list of allowed domains (empty = allow all)
FEDERATION_BLOCKLIST: Comma-separated list of blocked domains
SHARED_INBOX_ENABLED: Enable shared inbox (default: true)

Example:

# Block specific instances
FEDERATION_BLOCKLIST=spam.example.com,bad-actor.net

# Allow only specific instances
FEDERATION_ALLOWLIST=mastodon.social,misskey.io

Cache Configuration

REDIS_URL=redis://localhost:6379
CACHE_TTL=3600

Options:

REDIS_URL: Redis connection URL (optional, uses Dragonfly in Docker)
CACHE_TTL: Default cache TTL in seconds (default: 3600)

Queue Configuration

QUEUE_REDIS_URL=redis://localhost:6379
QUEUE_CONCURRENCY=10
QUEUE_MAX_RETRIES=3

Options:

QUEUE_REDIS_URL: Redis URL for BullMQ (defaults to REDIS_URL)
QUEUE_CONCURRENCY: Number of concurrent jobs (default: 10)
QUEUE_MAX_RETRIES: Max retry attempts for failed jobs (default: 3)

Rate Limiting

RATE_LIMIT_ENABLED=true
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

Options:

RATE_LIMIT_ENABLED: Enable rate limiting (default: true)
RATE_LIMIT_WINDOW_MS: Time window in milliseconds (default: 900000 = 15 min)
RATE_LIMIT_MAX_REQUESTS: Max requests per window (default: 100)

Email Configuration

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
[email protected]
SMTP_PASSWORD=your-app-password
[email protected]

Options:

SMTP_HOST: SMTP server host
SMTP_PORT: SMTP server port (587 for TLS, 465 for SSL)
SMTP_SECURE: Use SSL (default: false, use TLS)
SMTP_USER: SMTP username
SMTP_PASSWORD: SMTP password
SMTP_FROM: From email address

Logging Configuration

LOG_LEVEL=info
LOG_FORMAT=json

Options:

LOG_LEVEL: Logging level (debug, info, warn, error)
LOG_FORMAT: Log format (json or pretty)

Development Configuration

# Development only
DEV_CORS_ORIGIN=http://localhost:3001
DEV_SKIP_AUTH=false

Options:

DEV_CORS_ORIGIN: CORS origin for development
DEV_SKIP_AUTH: Skip authentication (DANGEROUS, dev only)

Configuration Files

wrangler.toml (Cloudflare Workers)

name = "rox"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[[d1_databases]]
binding = "DB"
database_name = "rox-db"
database_id = "your-database-id"

[[r2_buckets]]
binding = "MEDIA"
bucket_name = "rox-media"

[vars]
NODE_ENV = "production"
INSTANCE_NAME = "Your Instance"
INSTANCE_DESCRIPTION = "Your instance description"

docker-compose.yml

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: rox
      POSTGRES_USER: rox
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  dragonfly:
    image: docker.dragonflydb.io/dragonflydb/dragonfly
    ports:
      - "6379:6379"
    volumes:
      - dragonfly_data:/data

  backend:
    build: ./packages/backend
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=redis://dragonfly:6379
    depends_on:
      - postgres
      - dragonfly
    ports:
      - "3000:3000"

  frontend:
    build: ./packages/frontend
    environment:
      - BACKEND_URL=http://backend:3000
    depends_on:
      - backend
    ports:
      - "3001:3001"

volumes:
  postgres_data:
  dragonfly_data:

Configuration Best Practices

Security

Never commit .env files - Add to .gitignore
Use strong secrets - Minimum 32 characters, random
Rotate secrets regularly - Change JWT/session secrets periodically
Limit CORS origins - Only allow trusted domains
Enable HTTPS - Always use SSL/TLS in production

Performance

Enable caching - Configure Redis for better performance
Use CDN - Serve static assets through CDN
Optimize database - Add indexes for common queries
Configure connection pooling - Use PgBouncer for PostgreSQL

Reliability

Set up monitoring - Monitor health endpoints
Configure backups - Regular database backups
Use health checks - Configure Docker health checks
Set resource limits - Limit memory and CPU usage

Environment-Specific Configurations

Development

NODE_ENV=development
LOG_LEVEL=debug
LOG_FORMAT=pretty
DEV_CORS_ORIGIN=http://localhost:3001
RATE_LIMIT_ENABLED=false

Staging

NODE_ENV=production
LOG_LEVEL=info
LOG_FORMAT=json
RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_REQUESTS=200

Production

NODE_ENV=production
LOG_LEVEL=warn
LOG_FORMAT=json
COOKIE_SECURE=true
RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_REQUESTS=100

Troubleshooting

Database Connection Issues

# Test database connection
psql -h localhost -U rox -d rox

# Check DATABASE_URL format
echo $DATABASE_URL

Storage Issues

# Test S3 connection
aws s3 ls s3://your-bucket --endpoint-url=$S3_ENDPOINT

# Check local storage permissions
ls -la ./uploads

Redis Connection Issues

# Test Redis connection
redis-cli -u $REDIS_URL ping

Next Steps

Deployment Guide - Deploy Rox to production
Architecture Guide - Understand the architecture
API Reference - Explore the API