System Configuration

​

Overview

​

Environment Variables

​

Required Variables

​

JWT_SECRET

JWT_SECRET=your_secret_key_minimum_32_characters_long

• Purpose: Cryptographic key for signing and verifying JWT authentication tokens
• Requirements: Minimum 32 characters for production security
• Security: Never commit this value to version control
• Location: backend/config/env.js:8

​

ADMIN_PASSWORD

ADMIN_PASSWORD=secure_password_for_bootstrap

• Purpose: Password for the initial system administrator during bootstrap
• Usage: Only used during first-time initialization
• Security: Change immediately after system initialization
• Location: backend/domains/bootstrap/bootstrap.service.js:50

​

Optional Variables

​

PORT

PORT=3000

• Default: 3000
• Purpose: HTTP server port
• Location: backend/config/env.js:18

​

NODE_ENV

NODE_ENV=production

• Default: development
• Values: development, test, production
• Effects:
  • Controls cookie security flags (secure flag in production)
  • Determines database path (in-memory for test)
  • Affects logging verbosity
• Location: backend/config/env.js:21

​

DB_SOURCE

DB_SOURCE=mfcalidad.sqlite

• Default: mfcalidad.sqlite
• Purpose: SQLite database filename
• Location: Database stored in backend/database/
• Reference: backend/config/database.js:7

​

LOG_LEVEL

LOG_LEVEL=info

• Default: info
• Values: error, warn, info, http, verbose, debug
• Purpose: Winston logger output level
• Location: .env.example:23

​

DISABLE_AUTH_CHECKS

DISABLEAUTH_CHECKS=false

• Default: true (development mode)
• Purpose: Bypass role-based permission checks for development
• Security: MUST be set to false in production
• Effect: When true, all authenticated users have full system access
• Location: backend/middlewares/authorize.js:21

​

Configuration Files

​

Environment Configuration

// backend/config/env.js
const requiredEnv = ['JWT_SECRET', 'ADMIN_PASSWORD'];

requiredEnv.forEach((env) => {
  if (!process.env[env]) {
    console.error(`ERROR CRÍTICO: La variable de entorno ${env} es obligatoria.`);
    process.exit(1);
  }
});

​

Database Configuration

// backend/config/database.js
module.exports = {
  dbPath: path.resolve(__dirname, '../database', DB_SOURCE),
  adminPassword: ADMIN_PASSWORD
};

​

Database Management

​

SQLite Configuration

PRAGMA journal_mode = WAL;

• Enables concurrent reads during writes
• Improves performance for multi-user environments

PRAGMA foreign_keys = ON;

• Enforces referential integrity constraints
• Prevents orphaned records

PRAGMA synchronous = NORMAL;

• Balances performance and data safety
• Acceptable for most production workloads

​

Schema Migrations

1. Schema Detection: Checks existing table structure
2. Migration Execution: Applies schema changes transactionally
3. Data Preservation: Migrates existing data to new schema
4. Index Creation: Ensures performance indexes exist

• User domain redesign (persona-based access control)
• Audit logging enhancements
• Status field consolidation
• Absence management tracking

​

Seed Data

• Administrador
• Inspector
• Supervisor
• Jefe de Operaciones
• Gerencia
• Operario

• Producción
• Departamento de Calidad
• Mantenimiento
• Administración

• Tejedor
• Urdidor
• Mecánico
• Inspector de Calidad
• Auxiliar
• Supervisor de Planta

​

System Configuration Table

1. System starts with estado_sistema = 'NO_INICIALIZADO'
2. First admin user is created via bootstrap endpoint
3. State changes to INICIALIZADO
4. Normal authentication becomes available

​

Security Configuration

​

JWT Tokens

• Algorithm: Configurable (default: HS256)
• Expiration: 8 hours
• Payload: User ID, username, role, persona information

• HTTP-only cookie (browser protection)
• Authorization header (API clients)

res.cookie('token', result.token, {
  httpOnly: true,              // Prevents XSS access
  secure: NODE_ENV === 'production',  // HTTPS only in production
  sameSite: 'Strict',          // CSRF protection
  maxAge: 8 * 60 * 60 * 1000   // 8 hours
});

​

Password Security

• Algorithm: bcrypt
• Cost factor: 10
• Random salt per password

• Failed login tracking
• Automatic account lockout after 5 failed attempts
• Timing attack mitigation (constant-time comparison)
• Generic error messages (prevents user enumeration)

​

Session Management

const user = await sqlite.get(
  'SELECT estado_usuario FROM usuarios WHERE id = ?', 
  [decoded.usuario_id]
);

if (!user || user.estado_usuario !== 'Activo') {
  return next(new ForbiddenError('Su cuenta ha sido desactivada'));
}

​

Configuration Validation

​

Startup Checks

1. Environment validation: Required variables present
2. Database connectivity: SQLite file accessible
3. Schema integrity: Tables and indexes exist
4. Seed data: Default catalogs initialized
5. Logger initialization: Winston transport ready

​

Health Monitoring

• Database file size (growth rate)
• WAL file size (should auto-checkpoint)
• Failed login attempts (potential attacks)
• System initialization state
• Active user sessions

​

Production Checklist

​

Troubleshooting

​

Common Issues

• Check required environment variables are set
• Verify .env file exists and is readable
• Review startup logs for specific error

• Verify database file permissions
• Check disk space availability
• Ensure WAL mode is enabled

• Verify JWT_SECRET hasn’t changed (invalidates existing tokens)
• Check user account status in database
• Review failed login attempt count

• Verify DISABLE_AUTH_CHECKS is set correctly
• Check user role assignments
• Review permission mappings in backend/shared/auth/permissions.js

​

Related Documentation