Configuración#

Guía completa para configurar Construbot utilizando variables de entorno y archivos de configuración.

Descripción general#

Construbot utiliza un enfoque de configuración en capas:

  1. Archivos de configuración - Módulos de Python en construbot/config/settings/

  2. Variables de entorno - Cargadas desde el archivo .env o el entorno del sistema

  3. Configuración en tiempo de ejecución: configuración de Django controlada por el entorno

Esto sigue la metodología Twelve-Factor App para la gestión de la configuración.

Estructura de configuración#

Archivos de configuración#

Ubicado en construbot/config/settings/:

settings/
├── __init__.py
├── base.py          # Shared settings for all environments
├── local.py         # Development settings
├── test.py          # Testing settings
└── production.py    # Production settings

Selección:

El módulo de configuración activo está controlado por DJANGO_SETTINGS_MODULE:

# Development
export DJANGO_SETTINGS_MODULE=construbot.config.settings.local

# Production
export DJANGO_SETTINGS_MODULE=construbot.config.settings.production

Herencia:

Todos los archivos específicos del entorno heredan de base.py:

# local.py
from .base import *  # Import all base settings

# Override for development
DEBUG = True
ALLOWED_HOSTS = ['localhost', '127.0.0.1']

Variables de entorno#

Cargando variables#

Desde el archivo .env (recomendado para desarrollo):

# Enable .env file loading
export DJANGO_READ_DOT_ENV_FILE=True

Cree .env en la raíz del proyecto:

# .env
DJANGO_SETTINGS_MODULE=construbot.config.settings.local
DJANGO_DEBUG=True
DATABASE_URL=postgresql://user:pass@localhost:5432/construbot_dev

Desde el entorno del sistema:

# Export variables
export DJANGO_SETTINGS_MODULE=construbot.config.settings.production
export DJANGO_DEBUG=False
export DATABASE_URL=postgresql://...

En Docker Compose:

# docker-compose.yml
services:
  django:
    env_file:
      - ./.env
    environment:
      - DJANGO_SETTINGS_MODULE=construbot.config.settings.local

Variables requeridas#

Configuración central#

DJANGO_SETTINGS_MODULE

DJANGO_SETTINGS_MODULE=construbot.config.settings.local

Valores:

  • construbot.config.settings.local - Desarrollo

  • construbot.config.settings.test - Pruebas

  • construbot.config.settings.production - Producción

DJANGO_SECRET_KEY

DJANGO_SECRET_KEY=your-secret-key-here

Generar:

python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

Advertencia

¡Nunca envíe SECRET_KEY al control de versiones! Utilice claves diferentes para el desarrollo y la producción.

DJANGO_DEBUG

DJANGO_DEBUG=True   # Development
DJANGO_DEBUG=False  # Production

Peligro

¡Establezca siempre DEBUG=False en producción! El modo de depuración expone información confidencial.

Configuración de base de datos#

DATABASE_URL

# PostgreSQL (recommended)
DATABASE_URL=postgresql://user:password@host:port/database

# Examples:
# Local development:
DATABASE_URL=postgresql://construbot_user:construbot_pass@localhost:5432/construbot_dev

# Docker:
DATABASE_URL=postgresql://debug:debug@postgres:5432/construbot

# Production (with SSL):
DATABASE_URL=postgresql://user:pass@host:5432/db?sslmode=require

Formato: postgresql://[usuario]:[contraseña]@[host]:[puerto]/[base de datos]

Nota

Construbot usa django-environ para analizar DATABASE_URL en la configuración DATABASES de Django.

Caché y cola#

REDIS_URL

# Local development
REDIS_URL=redis://localhost:6379/0

# Docker
REDIS_URL=redis://redis:6379/0

# Production with password
REDIS_URL=redis://:password@host:6379/0

Utilizado para:

  • back-end de caché de Django

  • Corredor de mensajes de apio

  • Backend del resultado del apio

  • Almacenamiento de sesiones (opcional)

Variables opcionales#

Configuración de correo electrónico#

Desarrollo (backend de consola):

DJANGO_EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend

Los correos electrónicos se imprimen en la consola en lugar de enviarse.

Producción (SMTP):

DJANGO_EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password
EMAIL_USE_TLS=True

Usando django-anymail (recomendado):

# Mailgun
DJANGO_EMAIL_BACKEND=anymail.backends.mailgun.EmailBackend
MAILGUN_API_KEY=your-api-key
MAILGUN_SENDER_DOMAIN=mg.example.com

# SendGrid
DJANGO_EMAIL_BACKEND=anymail.backends.sendgrid.EmailBackend
SENDGRID_API_KEY=your-api-key

# Amazon SES
DJANGO_EMAIL_BACKEND=anymail.backends.amazon_ses.EmailBackend
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
AWS_SES_REGION_NAME=us-east-1

Predeterminado desde el correo electrónico:

DEFAULT_FROM_EMAIL=noreply@construbot.com
SERVER_EMAIL=errors@construbot.com

Archivos estáticos y multimedia#

Desarrollo (predeterminado):

# Static files served by Django
# Media files served from MEDIA_ROOT

Producción (T3):

# AWS S3 for media files
USE_S3=True
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_STORAGE_BUCKET_NAME=your-bucket-name
AWS_S3_REGION_NAME=us-east-1

# Optional: Custom domain
AWS_S3_CUSTOM_DOMAIN=cdn.example.com

Archivos estáticos (WhiteNoise):

No se necesita configuración. WhiteNoise está habilitado de forma predeterminada en la configuración de producción.

Anfitriones permitidos#

DJANGO_ALLOWED_HOSTS

# Development
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1

# Production (comma-separated)
DJANGO_ALLOWED_HOSTS=example.com,www.example.com,api.example.com

Advertencia

¡Requerido en producción! Django rechazará conexiones de hosts que no estén en esta lista.

Configuración CORS#

CORS_ALLOWED_ORIGINS

# Allow specific origins (recommended)
CORS_ALLOWED_ORIGINS=https://app.example.com,https://mobile.example.com

CORS_ALLOW_ALL_ORIGINS

# Development only - allow all origins
CORS_ALLOW_ALL_ORIGINS=True

Peligro

¡Nunca uses CORS_ALLOW_ALL_ORIGINS en producción! Solo permite orígenes confiables.

Configuración de la ventana acoplable#

USE_DOCKER

USE_DOCKER=yes  # Docker environment
USE_DOCKER=no   # Local environment

Esto afecta:

  • Host de base de datos (postgres vs localhost)

  • Anfitrión de Redis (redis frente a localhost)

  • Host de correo electrónico (mailhog vs localhost SMTP)

Modo biblioteca#

CONSTRUBOT_AS_LIBRARY

CONSTRUBOT_AS_LIBRARY=False  # Standalone mode (default)
CONSTRUBOT_AS_LIBRARY=True   # Library mode

Cuando es «Verdadero»:

  • Deshabilita la interfaz de administración

  • Deshabilita las URL de administración de cuentas

  • Deshabilita la autenticación independiente

  • Utilice Construbot como aplicación Django en su proyecto

Consulte Modo biblioteca para obtener más detalles.

Integración centinela#

SENTRY_DSN

SENTRY_DSN=https://your-dsn@sentry.io/project-id

SENTRY_ENVIRONMENT

SENTRY_ENVIRONMENT=production  # or staging, development

SENTRY_SAMPLE_RATE

# 1.0 = 100% of errors sent to Sentry
SENTRY_SAMPLE_RATE=1.0

Explotación florestal#

LOG_LEVEL

LOG_LEVEL=INFO   # Production
LOG_LEVEL=DEBUG  # Development

Valores: DEPURACIÓN, INFORMACIÓN, ADVERTENCIA, ERROR, CRÍTICO

Configuración de apio#

APIO_BROKER_URL

CELERY_BROKER_URL=redis://redis:6379/0

Generalmente igual que REDIS_URL.

Apio_RESULT_BACKEND

CELERY_RESULT_BACKEND=redis://redis:6379/0

APIO_TASK_ALWAYS_EAGER

# Execute tasks synchronously (testing)
CELERY_TASK_ALWAYS_EAGER=True

Configuración por entorno#

Desarrollo (.env)#

Archivo .env completo para desarrollo local:

# Django Settings
DJANGO_SETTINGS_MODULE=construbot.config.settings.local
DJANGO_DEBUG=True
DJANGO_READ_DOT_ENV_FILE=True
DJANGO_SECRET_KEY=dev-secret-key-change-in-production

# Docker
USE_DOCKER=yes  # Set to 'no' for local development

# Database (Docker)
DATABASE_URL=postgresql://debug:debug@postgres:5432/construbot

# Database (Local)
# DATABASE_URL=postgresql://construbot_user:construbot_pass@localhost:5432/construbot_dev

# Redis
REDIS_URL=redis://redis:6379/0

# Email (Console)
DJANGO_EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend

# Celery
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/0

# Allowed Hosts
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1,0.0.0.0

# CORS (Development only)
CORS_ALLOW_ALL_ORIGINS=True

Pruebas#

Entorno para ejecutar pruebas:

# Settings
DJANGO_SETTINGS_MODULE=construbot.config.settings.test
DJANGO_DEBUG=False
DJANGO_SECRET_KEY=test-secret-key

# Database (in-memory SQLite)
# No DATABASE_URL needed - test settings use SQLite

# Celery (synchronous execution)
CELERY_TASK_ALWAYS_EAGER=True

Producción#

Variables del entorno de producción:

# Django Settings
DJANGO_SETTINGS_MODULE=construbot.config.settings.production
DJANGO_DEBUG=False
DJANGO_SECRET_KEY=<generate-strong-secret-key>

# Security
DJANGO_SECURE_SSL_REDIRECT=True
DJANGO_SECURE_HSTS_SECONDS=31536000
DJANGO_SESSION_COOKIE_SECURE=True
DJANGO_CSRF_COOKIE_SECURE=True

# Database (with SSL)
DATABASE_URL=postgresql://user:pass@host:5432/db?sslmode=require

# Redis
REDIS_URL=redis://:password@host:6379/0

# Email (Production service)
DJANGO_EMAIL_BACKEND=anymail.backends.mailgun.EmailBackend
MAILGUN_API_KEY=<your-api-key>
MAILGUN_SENDER_DOMAIN=mg.example.com
DEFAULT_FROM_EMAIL=noreply@example.com

# Static/Media Files (S3)
USE_S3=True
AWS_ACCESS_KEY_ID=<your-key>
AWS_SECRET_ACCESS_KEY=<your-secret>
AWS_STORAGE_BUCKET_NAME=construbot-media
AWS_S3_REGION_NAME=us-east-1

# Allowed Hosts (comma-separated)
DJANGO_ALLOWED_HOSTS=example.com,www.example.com,api.example.com

# CORS (specific origins only)
CORS_ALLOWED_ORIGINS=https://app.example.com

# Sentry
SENTRY_DSN=<your-sentry-dsn>
SENTRY_ENVIRONMENT=production

# Logging
LOG_LEVEL=INFO

Configuración de seguridad#

Lista de verificación de seguridad de producción#

# HTTPS Enforcement
DJANGO_SECURE_SSL_REDIRECT=True
DJANGO_SECURE_PROXY_SSL_HEADER=HTTP_X_FORWARDED_PROTO,https

# HSTS (HTTP Strict Transport Security)
DJANGO_SECURE_HSTS_SECONDS=31536000
DJANGO_SECURE_HSTS_INCLUDE_SUBDOMAINS=True
DJANGO_SECURE_HSTS_PRELOAD=True

# Cookie Security
DJANGO_SESSION_COOKIE_SECURE=True
DJANGO_SESSION_COOKIE_HTTPONLY=True
DJANGO_CSRF_COOKIE_SECURE=True
DJANGO_CSRF_COOKIE_HTTPONLY=True

# Content Security
DJANGO_SECURE_CONTENT_TYPE_NOSNIFF=True
DJANGO_SECURE_BROWSER_XSS_FILTER=True
X_FRAME_OPTIONS=DENY

Ejecutar control de seguridad:

python manage.py check --deploy

Gestión de la configuración#

Plantilla de archivo de entorno#

Cree .env.example como plantilla:

# Copy for local use: cp .env.example .env

# Django
DJANGO_SETTINGS_MODULE=construbot.config.settings.local
DJANGO_DEBUG=True
DJANGO_SECRET_KEY=change-me

# Database
DATABASE_URL=postgresql://user:pass@host:port/database

# ... (include all required variables with examples)

Beneficios:

  • Documentos variables requeridas

  • Proporciona ejemplos para desarrolladores.

  • Seguro para cometer (sin secretos)

Gestión de secretos#

Desarrollo:

  • Utilice el archivo .env (git-ignorado)

  • Compartir plantilla .env.example

Producción:

  • Utilice variables de entorno (no archivos .env)

  • Almacenar secretos en una bóveda segura (AWS Secrets Manager, HashiCorp Vault)

  • Inyectar secretos en tiempo de ejecución

Ejemplo con AWS Secrets Manager:

# In settings/production.py
import boto3
import json

def get_secret(secret_name):
    client = boto3.client('secretsmanager')
    response = client.get_secret_value(SecretId=secret_name)
    return json.loads(response['SecretString'])

secrets = get_secret('construbot/production')
SECRET_KEY = secrets['DJANGO_SECRET_KEY']
DATABASE_URL = secrets['DATABASE_URL']

Validación de configuración#

Verifique las variables requeridas:

# Django checks
python manage.py check

# Deployment checks
python manage.py check --deploy

# Database connection
python manage.py dbshell

Configuración de correo electrónico de prueba:

python manage.py shell

>>> from django.core.mail import send_mail
>>> send_mail('Test', 'Message', 'from@example.com', ['to@example.com'])

Solución de problemas#

Problemas comunes#

«Configurado incorrectamente: establezca la variable de entorno DATABASE_URL»

# Ensure DATABASE_URL is set
echo $DATABASE_URL

# Or add to .env
DATABASE_URL=postgresql://...

«Se requiere SECRET_KEY»

# Generate and set SECRET_KEY
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

# Add to .env
DJANGO_SECRET_KEY=<generated-key>

«CommandError: debes establecer la configuración.ALLOWED_HOSTS»

# Add to .env
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1

«Host no permitido en /»

# Add your domain to ALLOWED_HOSTS
DJANGO_ALLOWED_HOSTS=example.com,www.example.com

Las variables no se cargan desde .env

# Ensure this is set
DJANGO_READ_DOT_ENV_FILE=True

# Check .env is in project root (same directory as manage.py)
ls -la .env

Prioridad de variables#

Si una variable se establece en varios lugares, este es el orden de prioridad:

  1. Variables de entorno del sistema (prioridad más alta)

  2. archivo .env

  3. Valores predeterminados del archivo de configuración (prioridad más baja)

Ejemplo:

# .env
DJANGO_DEBUG=True

# Terminal
export DJANGO_DEBUG=False

# Django will use DEBUG=False (system environment wins)

Ver también#