Skip to main content

​
Overview

Kontrak Backend uses environment variables for configuration. All settings are loaded from a .env file and accessed through a centralized configuration module.

​
Environment Variables

​
Server Configuration

​
NODE_ENV
string
default:"development"
Application environment. Set to production for production deployments.
​
PORT
number
default:"3000"
Port number where the server will listen for requests.
​
HOST
string
default:"localhost"
Hostname for the server. Use 0.0.0.0 to accept connections from any network interface.

​
CORS Configuration

​
CORS_ORIGINS
string
default:"http://localhost:3000,http://localhost:5173"
Comma-separated list of allowed origins for CORS requests.Example:
CORS_ORIGINS=http://localhost:3000,https://app.example.com,https://admin.example.com
The CORS middleware will log blocked origins to help you debug access issues. Check your server logs if you’re experiencing CORS errors.

​
File Limits

​
MAX_FILE_SIZE
number
default:"10485760"
Maximum file size in bytes. Default is 10MB (10485760 bytes).
​
MAX_EMPLOYEES
number
default:"1000"
Maximum number of employees that can be processed in a single batch operation.

​
Directories

​
TEMP_DIR
string
default:"./temp"
Directory path for storing temporary files during contract generation.

​
Timeouts & Cleanup

​
FILE_CLEANUP_TIMEOUT
number
default:"3600000"
Timeout in milliseconds before temporary files are cleaned up. Default is 1 hour (3600000ms).

​
Configuration File Structure

The configuration is centralized in src/config/index.ts: 
export const config = {
  server: {
    env: process.env.NODE_ENV || 'development',
    port: parseInt(process.env.PORT || '3000', 10),
    host: process.env.HOST || 'localhost',
  },
  cors: {
    origins: process.env.CORS_ORIGINS || ['http://localhost:5173'],
  },
  limits: {
    maxFileSize: parseInt(process.env.MAX_FILE_SIZE || '10485760', 10),
    maxEmployees: parseInt(process.env.MAX_EMPLOYEES || '1000', 10),
  },
  paths: {
    temp: path.resolve(process.env.TEMP_DIR || './temp'),
    templates: path.resolve('./src/templates'),
  },
};

​
Setting Up Your Environment

1

Copy the example file

Create your .env file from the example:
cp .env.example .env
2

Configure for your environment

Edit .env with your specific settings:
NODE_ENV=development
PORT=3000
HOST=localhost
CORS_ORIGINS=http://localhost:3000,http://localhost:5173
MAX_FILE_SIZE=10485760
MAX_EMPLOYEES=1000
FILE_CLEANUP_TIMEOUT=3600000
TEMP_DIR=./temp
3

Create required directories

Ensure the temp directory exists:
mkdir -p temp

​
CORS Setup Details

The CORS configuration (src/config/cors.config.ts) supports:
  • Dynamic origin validation: Only whitelisted origins are allowed
  • Logging: Blocked origins are logged for debugging
  • HTTP Methods: GET, POST, PUT, DELETE, PATCH
export const corsConfig: CorsOptions = {
  origin: (origin, callback) => {
    const whiteList = process.env.CORS_ORIGINS
      ? process.env.CORS_ORIGINS.split(',').map((url) => url.trim())
      : ['http://localhost:5173'];

    if (!origin || whiteList.includes(origin)) {
      callback(null, true);
    } else {
      callback(new Error('Not allowed by CORS'));
    }
  },
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
};

​
Production Settings

Always configure these settings properly for production deployments.
# Production Environment
NODE_ENV=production
PORT=8080
HOST=0.0.0.0

# CORS - Add your production domains
CORS_ORIGINS=https://app.yourdomain.com,https://admin.yourdomain.com

# File Limits - Adjust based on your needs
MAX_FILE_SIZE=20971520  # 20MB for production
MAX_EMPLOYEES=500       # Limit batch size

# Cleanup - Clean up files faster in production
FILE_CLEANUP_TIMEOUT=1800000  # 30 minutes

# Directories - Use absolute paths
TEMP_DIR=/var/app/temp

​
Security Considerations

  • Never use wildcards (*) in production
  • Only whitelist domains you own and control
  • Include all subdomains that need access
  • Use HTTPS URLs in production
  • Set MAX_FILE_SIZE based on your server capacity
  • Too large files can cause memory issues
  • Consider implementing virus scanning for uploaded files
  • Ensure TEMP_DIR has adequate disk space
  • Configure FILE_CLEANUP_TIMEOUT to prevent disk filling
  • Consider using a separate partition for temp files
  • Implement monitoring for disk usage
  • Never commit .env files to version control
  • Use secret management systems in production
  • Rotate sensitive credentials regularly
  • Validate all environment variables on startup

​
Validating Configuration

The application validates critical configuration on startup: 
export const validateConfig = (): void => {
  const isDevelopment = config.server.env === 'development';

  if (!isDevelopment && !process.env.PORT) {
    console.warn('WARNING: PORT no está configurado en producción');
  }

  console.info('Configuración cargada:', {
    env: config.server.env,
    port: config.server.port,
    host: config.server.host,
  });
};

​
Troubleshooting

​
Port Already in Use

If you get an EADDRINUSE error: 
# Change the port in .env
PORT=3001

​
CORS Errors

Check server logs for blocked origins: 
🚫 CORS Bloqueado: http://localhost:8080
✅ Permitidos: ['http://localhost:3000', 'http://localhost:5173']
Add the blocked origin to CORS_ORIGINS.

​
File Upload Errors

If files fail to upload:
  1. Check MAX_FILE_SIZE setting
  2. Verify TEMP_DIR exists and is writable
  3. Ensure sufficient disk space

​
Configuration Not Loading

  1. Verify .env file is in the project root
  2. Check for syntax errors in .env
  3. Restart the server after changes
  4. Review startup logs for configuration warnings

​
Next Steps

Generating Contracts

Learn how to generate employment contracts

Excel Upload

Understand Excel file format requirements

Build docs developers (and LLMs) love

Get started for freeTalk to us