Configuration Guide

CUIDO Backend uses environment variables for configuration. This guide documents all available options with detailed explanations and examples.

Environment File Setup

Create a .env file in the project root:

cp .env.example .env

Never commit your .env file to version control. It contains sensitive credentials. The .gitignore file should already exclude it.

Core Configuration

Server Settings

PORT

number

default:"3000"

The port number on which the server will listen for incoming requests.

PORT=3000

Common ports:

3000 - Default development
8080 - Alternative development
80 - HTTP production (requires privileges)
443 - HTTPS production (requires privileges)

NODE_ENV

string

default:"development"

The application environment mode. Affects logging, error handling, and security settings.

NODE_ENV=development

Valid values:

development - Verbose logging, detailed errors, hot reload
production - Minimal logging, sanitized errors, optimizations
test - Test mode, in-memory database, mocked services

Database Configuration

MongoDB Connection

MONGODB_URI

string

required

MongoDB connection string. Supports both local and cloud (Atlas) connections.

# Local MongoDB
MONGODB_URI=mongodb://localhost:27017/claude-prompt-db

# MongoDB Atlas
MONGODB_URI=mongodb+srv://username:[email protected]/claude-prompt-db?retryWrites=true&w=majority

# MongoDB with authentication
MONGODB_URI=mongodb://admin:password@localhost:27017/claude-prompt-db?authSource=admin

Connection string components:

mongodb:// or mongodb+srv:// - Protocol
username:password@ - Credentials (optional for local)
localhost:27017 - Host and port
/claude-prompt-db - Database name
?options - Connection options

The database connection uses these Mongoose options:

maxPoolSize: 10 - Maximum 10 concurrent connections
serverSelectionTimeoutMS: 5000 - 5 second timeout
socketTimeoutMS: 45000 - 45 second socket timeout

Authentication & Security

JWT Configuration

JWT_SECRET

string

required

Secret key for signing and verifying JSON Web Tokens. Must be kept secure.

JWT_SECRET=your_jwt_secret_super_secure_256_bits_minimum

Best practices:

Minimum 32 characters
Mix of letters, numbers, and symbols
Generate with: openssl rand -base64 32
Different for each environment
Never reuse across projects

JWT_EXPIRES_IN

string

default:"7d"

Token expiration time. Uses vercel/ms format.

JWT_EXPIRES_IN=7d

Valid formats:

60 - 60 seconds
5m - 5 minutes
2h - 2 hours
7d - 7 days
30d - 30 days

JWT Implementation Details: The authentication system in src/services/authService.js:9 uses:

jwt.sign(
  payload,
  process.env.JWT_SECRET,
  { expiresIn: process.env.JWT_EXPIRES_IN || '7d' }
)

Tokens are verified in src/services/authService.js:20:

jwt.verify(token, process.env.JWT_SECRET)

Anthropic Claude AI

API Configuration

ANTHROPIC_API_KEY

string

required

Your Anthropic API key for Claude AI integration. Get it from console.anthropic.com.

ANTHROPIC_API_KEY=sk-ant-api03-your-actual-api-key-here

Key format validation:

Must start with sk-ant-
Validated on server startup (server.js:31-38)
Connection tested before server starts

CLAUDE_MODEL

string

default:"claude-3-sonnet-20240229"

The Claude model to use for completions. Different models offer different performance/cost tradeoffs.

CLAUDE_MODEL=claude-3-sonnet-20240229

Available models:

Model	Best For	Speed	Cost
`claude-3-opus-20240229`	Complex tasks, highest accuracy	Slower	Highest
`claude-3-sonnet-20240229`	Balanced (recommended)	Medium	Medium
`claude-3-haiku-20240307`	Simple tasks, high volume	Fastest	Lowest

API Key Validation: The server validates the Anthropic configuration on startup (server.js:31-46):

if (!process.env.ANTHROPIC_API_KEY) {
  logger.error('ANTHROPIC_API_KEY no está configurada en el archivo .env');
  process.exit(1);
}

if (!process.env.ANTHROPIC_API_KEY.startsWith('sk-ant-')) {
  logger.error('ANTHROPIC_API_KEY no tiene el formato correcto');
  process.exit(1);
}

The server tests Claude API connectivity before starting. If validation fails, check your API key and network connection.

CORS & Security

ALLOWED_ORIGINS

string

Comma-separated list of allowed origins for CORS.

ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173,https://app.example.com

Implementation (src/app.js:51):

const allowedOrigins = process.env.ALLOWED_ORIGINS?.split(',') || [
  'http://localhost:3000',
  'http://localhost:5173',
  'http://localhost:8080'
];

SOCKET_IO_CORS_ORIGINS

string

Comma-separated list of allowed origins for Socket.IO connections.

SOCKET_IO_CORS_ORIGINS=http://localhost:3000,https://app.example.com

Implementation (server.js:65):

const io = new Server(httpServer, {
  cors: {
    origin: process.env.SOCKET_IO_CORS_ORIGINS?.split(',') || [
      'http://localhost:3000',
      'http://localhost:5173',
      'http://localhost:8080'
    ]
  }
});

Rate Limiting

Global Rate Limits

RATE_LIMIT_WINDOW_MS

number

default:"900000"

Time window for rate limiting in milliseconds.

RATE_LIMIT_WINDOW_MS=900000  # 15 minutes

Common values:

60000 - 1 minute
300000 - 5 minutes
900000 - 15 minutes (default)
3600000 - 1 hour

RATE_LIMIT_MAX_REQUESTS

number

default:"100"

Maximum number of requests allowed per IP in the time window.

RATE_LIMIT_MAX_REQUESTS=100

Implementation (src/app.js:72-74):

const limiter = rateLimit({
  windowMs: parseInt(process.env.RATE_LIMIT_WINDOW_MS) || 15 * 60 * 1000,
  max: parseInt(process.env.RATE_LIMIT_MAX_REQUESTS) || 100,
  // ... handlers
});

Endpoint-Specific Limits

Authentication endpoints (src/routes/authRoutes.js:12-14):

Window: 15 minutes
Max requests: 5 per IP
Applies to: /api/auth/login, /api/auth/register

Chat endpoints (src/routes/chatRoutes.js:17-19):

Window: 1 minute
Max requests: 10 per user
Applies to: /api/chat/complete

Rate limits are enforced per IP address for public endpoints and per user for authenticated endpoints. Exceeding limits returns HTTP 429.

Logging Configuration

Winston Logger Settings

LOG_LEVEL

string

default:"info"

Minimum log level to record.

LOG_LEVEL=info

Log levels (highest to lowest priority):

error - Only errors
warn - Errors and warnings
info - Standard operational info (recommended)
http - HTTP requests
verbose - Detailed info
debug - Debug information
silly - Everything

LOG_FILE_PATH

string

default:"./logs"

Directory path for log files. Created automatically if it doesn’t exist.

LOG_FILE_PATH=./logs

Log rotation (src/utils/logger.js):

Daily rotation via winston-daily-rotate-file
Pattern: application-%DATE%.log
Error logs: error-%DATE%.log
Max file size: 20MB
Max files: 14 days

Logging behavior by environment:

// Development (src/app.js:119)
const morganFormat = process.env.NODE_ENV === 'production' ? 'combined' : 'dev';

Development: Colorized console output, verbose errors
Production: JSON format, sanitized error messages

Scheduled Tasks

Cron Jobs

ENABLE_CRON_JOBS

boolean

default:"false"

Enable or disable scheduled background tasks.

ENABLE_CRON_JOBS=true

Implementation (server.js:106-108):

if (process.env.ENABLE_CRON_JOBS === 'true') {
  scheduledTasks.init();
}

Valid values:

true - Enable scheduled tasks
false - Disable scheduled tasks

Scheduled tasks use node-cron for:

Periodic data cleanup
Analytics aggregation
Notification processing
Health checks

Complete .env Template

Here’s a complete template with all available options:

# ===================================
# CUIDO Backend Configuration
# ===================================

# -----------------------------------
# Server Configuration
# -----------------------------------
PORT=3000
NODE_ENV=development

# -----------------------------------
# Database Configuration
# -----------------------------------
# Local MongoDB
MONGODB_URI=mongodb://localhost:27017/claude-prompt-db

# MongoDB Atlas (Cloud)
# MONGODB_URI=mongodb+srv://username:[email protected]/claude-prompt-db?retryWrites=true&w=majority

# -----------------------------------
# JWT Authentication
# -----------------------------------
# Generate a secure secret: openssl rand -base64 32
JWT_SECRET=your_jwt_secret_super_secure_256_bits_minimum_change_this
JWT_EXPIRES_IN=7d

# -----------------------------------
# Anthropic Claude AI
# -----------------------------------
# Get your API key: https://console.anthropic.com/
ANTHROPIC_API_KEY=sk-ant-api03-your-actual-api-key-here
CLAUDE_MODEL=claude-3-sonnet-20240229

# Available models:
# - claude-3-opus-20240229    (highest capability, highest cost)
# - claude-3-sonnet-20240229  (balanced, recommended)
# - claude-3-haiku-20240307   (fastest, lowest cost)

# -----------------------------------
# CORS Configuration
# -----------------------------------
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173,http://localhost:8080
SOCKET_IO_CORS_ORIGINS=http://localhost:3000,http://localhost:5173,http://localhost:8080

# Production example:
# ALLOWED_ORIGINS=https://app.example.com,https://www.example.com
# SOCKET_IO_CORS_ORIGINS=https://app.example.com

# -----------------------------------
# Rate Limiting
# -----------------------------------
RATE_LIMIT_WINDOW_MS=900000        # 15 minutes in milliseconds
RATE_LIMIT_MAX_REQUESTS=100        # Max requests per IP per window

# Recommended values:
# Development: RATE_LIMIT_MAX_REQUESTS=1000
# Production: RATE_LIMIT_MAX_REQUESTS=100

# -----------------------------------
# Logging Configuration
# -----------------------------------
LOG_LEVEL=info                     # error | warn | info | debug
LOG_FILE_PATH=./logs               # Log file directory

# -----------------------------------
# Scheduled Tasks
# -----------------------------------
ENABLE_CRON_JOBS=false             # true | false

# -----------------------------------
# Optional: Performance Tuning
# -----------------------------------
# Body parser limits (configured in src/app.js:99-113)
# Default: 10mb for JSON and URL-encoded bodies

# MongoDB connection pool (configured in src/config/database.js:8-12)
# Default: maxPoolSize=10, socketTimeout=45000ms

Environment-Specific Configurations

Development

NODE_ENV=development
PORT=3000
MONGODB_URI=mongodb://localhost:27017/claude-prompt-db-dev
LOG_LEVEL=debug
RATE_LIMIT_MAX_REQUESTS=1000
ENABLE_CRON_JOBS=false

Production

NODE_ENV=production
PORT=3000
MONGODB_URI=mongodb+srv://prod_user:[email protected]/cuido_prod
JWT_SECRET=<generated-with-openssl-rand-base64-64>
JWT_EXPIRES_IN=24h
ANTHROPIC_API_KEY=sk-ant-api03-production-key
CLAUDE_MODEL=claude-3-sonnet-20240229
ALLOWED_ORIGINS=https://cuido.example.com
SOCKET_IO_CORS_ORIGINS=https://cuido.example.com
LOG_LEVEL=info
RATE_LIMIT_MAX_REQUESTS=100
ENABLE_CRON_JOBS=true

Testing

NODE_ENV=test
PORT=3001
MONGODB_URI=mongodb://localhost:27017/claude-prompt-db-test
LOG_LEVEL=error
RATE_LIMIT_MAX_REQUESTS=10000
ENABLE_CRON_JOBS=false

Security Best Practices

Generate Strong Secrets

Use cryptographically secure random strings:

# Generate JWT secret (32 bytes, base64 encoded)
openssl rand -base64 32

# Generate longer secret (64 bytes)
openssl rand -base64 64

Use Different Credentials Per Environment

Never use the same JWT_SECRET or ANTHROPIC_API_KEY across development, staging, and production.

Restrict CORS Origins

In production, only allow specific domains:

# Bad (development only)
ALLOWED_ORIGINS=*

# Good (production)
ALLOWED_ORIGINS=https://app.example.com,https://www.example.com

Protect Your .env File

Ensure .env is in .gitignore:

# Check if .env is ignored
git check-ignore .env

# Add to .gitignore if not present
echo ".env" >> .gitignore

Use Environment-Specific Files

Consider using different env files:

.env.development
.env.production
.env.test

Load with:

NODE_ENV=production node -r dotenv/config server.js dotenv_config_path=.env.production

Validation on Startup

The server validates critical configuration on startup:

// src/config/database.js:4-50
if (!process.env.MONGODB_URI) {
  logger.error('MONGODB_URI not configured');
  process.exit(1);
}

Next Steps

Quick Start

Start using CUIDO Backend

Authentication

Learn about the auth system

Deployment

Deploy to production

Architecture

Understand the system architecture

Troubleshooting

Server exits with 'ANTHROPIC_API_KEY not configured'

Ensure your .env file contains:

ANTHROPIC_API_KEY=sk-ant-api03-...

And that the key starts with sk-ant-.

MongoDB connection fails

Check:

MongoDB is running: sudo systemctl status mongod
MONGODB_URI is correct in .env
Network connectivity if using MongoDB Atlas
Firewall rules allow connection to port 27017

JWT tokens not working

Verify:

JWT_SECRET is set and not empty
Same secret used for signing and verification
Token hasn’t expired (check JWT_EXPIRES_IN)

CORS errors in browser

Add your frontend URL to ALLOWED_ORIGINS:

ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173,YOUR_FRONTEND_URL

Restart the server after changing .env.

Rate limit blocking legitimate requests

Increase limits for development:

RATE_LIMIT_MAX_REQUESTS=1000

Or disable temporarily by commenting out the rate limiter in src/app.js:96.

Getting Started

Core Concepts

Modules

Development

Configuration

Configuration Guide

Environment File Setup

Core Configuration

Server Settings

Database Configuration

MongoDB Connection

Authentication & Security

JWT Configuration

Anthropic Claude AI

API Configuration

CORS & Security

Rate Limiting

Global Rate Limits

Endpoint-Specific Limits

Logging Configuration

Winston Logger Settings

Scheduled Tasks

Cron Jobs

Complete .env Template

Environment-Specific Configurations

Development

Production

Testing

Security Best Practices

Validation on Startup

Next Steps

Quick Start

Authentication

Deployment

Architecture

Troubleshooting

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Modules

Development

​Configuration Guide

​Environment File Setup

​Core Configuration

​Server Settings

​Database Configuration

​MongoDB Connection

​Authentication & Security

​JWT Configuration

​Anthropic Claude AI

​API Configuration

​CORS & Security

​Cross-Origin Resource Sharing

​Rate Limiting

​Global Rate Limits

​Endpoint-Specific Limits

​Logging Configuration

​Winston Logger Settings

​Scheduled Tasks

​Cron Jobs

​Complete .env Template

​Environment-Specific Configurations

​Development

​Production

​Testing

​Security Best Practices

​Validation on Startup

​Next Steps

Quick Start

Authentication

Deployment

Architecture

​Troubleshooting

Build docs developers (and LLMs) love

Configuration Guide

Environment File Setup

Core Configuration

Server Settings

Database Configuration

MongoDB Connection

Authentication & Security

JWT Configuration

Anthropic Claude AI

API Configuration

CORS & Security

Cross-Origin Resource Sharing

Rate Limiting

Global Rate Limits

Endpoint-Specific Limits

Logging Configuration

Winston Logger Settings

Scheduled Tasks

Cron Jobs

Complete .env Template

Environment-Specific Configurations

Development

Production

Testing

Security Best Practices

Validation on Startup

Next Steps

Troubleshooting