Para gestionar aplicaciones web basadas en Python mediante Gunicorn, el uso de un archivo de configuración permite centralizar parámetros complejos que van más allá de lo que se puede definir cómodamente en la línea de comandos. A continuación, se presenta un ejemplo estructurado de un archivo gunicorn_config.py diseñado para entornos de producción y desarrollo.

import os
import multiprocessing

# Localización de la aplicación
# Formato: 'modulo:objeto_aplicacion'
wsgi_app = 'api.main:app'

# Definición de rutas base
RUTA_RAIZ = os.path.dirname(os.path.abspath(__file__))

# Configuración del servidor
bind = '0.0.0.0:5000'
backlog = 2048

# Control de procesos (Workers)
# Se ajusta la cantidad de procesos según el entorno detectado
entorno_actual = os.getenv('APP_ENV', 'produccion')

if entorno_actual == 'desarrollo':
    workers = 2
    reload = True  # Reinicio automático al detectar cambios en el código
else:
    # Fórmula recomendada: (2 x cores) + 1
    workers = multiprocessing.cpu_count() * 2 + 1
    reload = False

# Clase de worker: 'sync', 'gevent', 'eventlet', 'gthread'
# Gevent es ideal para manejar múltiples peticiones concurrentes en I/O
worker_class = 'gevent'
worker_connections = 1000

# Gestión de tiempos de espera
timeout = 120
keepalive = 5

# Registro de actividad (Logging)
daemon = False  # Se mantiene en False para facilitar la captura de logs en Docker/K8s
pidfile = os.path.join(RUTA_RAIZ, 'gunicorn_proceso.pid')

# '-' indica que los logs se enviarán a la salida estándar (stdout/stderr)
accesslog = '-'
errorlog = '-'
loglevel = 'info'

# Personalización del formato de logs de acceso
access_log_format = '%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s"'

# Prevención de fugas de memoria
# Reinicia el worker después de procesar un número determinado de peticiones
max_requests = 1000
max_requests_jitter = 50

Parámetros fnudamentales de la línea de comandos

Aunque el archivo de configuración es la forma preferida de gestionar Gunicorn, es crucial conocer las opciones equivalentes que ofrece la interfaz de comandos (CLI) para ajustes rápidos o scripts de inicio.

• -c CONFIG, --config CONFIG: Especifica la ruta del archivo de configuración. Ejemplo: gunicorn -c gunicorn_config.py app:app.
• -b BIND, --bind BIND: Define la interfaz y el puerto de escucha.
• -w WORKERS, --workers WORKERS: Define el número de procesos de trabajo.
• -k STRING, --worker-class STRING: Determina el tipo de gestión de hilos/procesos (por defecto es sync).
• --timeout INT: Tiempo máximo que un worker puede estar inactivo antes de ser reiniciado por el proceso maestro.
• --max-requests INT: Límite de peticiones por worker antes de forzar un reinicio preventivo.
• --capture-output: Redirecciona la salida estándar y de error directamente a los archivos de log configurados.

Hooks de ciclo de vida

Gunicorn permite definir funciones dentro del archivo de cnofiguración para ejecutar lógica en momentos específicos del ciclo de vida del servidor:

def on_starting(server):
    """Ejecutado justo antes de que el proceso maestro comience."""
    pass

def post_fork(server, worker):
    """Ejecutado inmediatamente después de que un worker ha sido creado."""
    server.log.info("Worker generado con PID: %s", worker.pid)

def worker_exit(server, worker):
    """Ejecutado al finalizar un proceso worker."""
    server.log.info("Finalizando worker con PID: %s", worker.pid)

Esta estructura de configuración permite una transición fluida entre servidores locales de prueba y clústeres de producción de alta disponibilidad, garantizando que el comportamiento del servidor sea predecible y fácil de depurar.