Cómo Configurar Gunicorn en Producción en Square Cloud

Si has estado desarrollando aplicaciones web con Python usando frameworks como Django o Flask, sabes que ejecutar el servidor de desarrollo integrado (flask run o python app.py) no es una opción para el mundo real. No soportan la carga de múltiples solicitudes simultáneas.

Para poner tu aplicación en producción con rendimiento y estabilidad, necesitas un servidor WSGI probado en el campo de batalla: Gunicorn (Green Unicorn).

A continuación, descubre cómo orquestar Gunicorn perfectamente dentro del entorno de Square Cloud, que ya se encarga del host 0.0.0.0 y del puerto por defecto 80 por ti.

1. Declarar las Dependencias

Dado que Square se encarga de la instalación de forma automática, tu único trabajo es asegurarte de que Gunicorn esté listado como una dependencia del proyecto.

Si utilizas requirements.txt, añade la línea:

gunicorn

Si tu proyecto utiliza el estándar oficial pyproject.toml (PEP 621), añádelo en la sección de dependencias del proyecto:

[project]
dependencies = [
    "gunicorn>=23.0.0",
]

Al subir el proyecto, Square leerá estos archivos y dejará el módulo de Gunicorn listo para usar.

2. Entendiendo el Comando

Para garantizar que Gunicorn se ejecute exactamente mediante el intérprete de Python aislado de tu contenedor en Square, la buena práctica es llamarlo como un módulo utilizando la bandera -m:

python -m gunicorn [opciones] nombre_del_modulo:atributo_de_la_aplicacion

• nombre_del_modulo: Es el nombre del archivo .py donde está tu aplicación (ej: main o wsgi).
• atributo_de_la_aplicacion: Es la variable que recibe la instancia de tu framework (generalmente llamada app o application).

Ejemplo Práctico con Flask

Si tienes un archivo en la raíz llamado wsgi.py:

from mi_proyecto import app

if __name__ == "__main__":
    app.run()

El comando para que Gunicorn gestione esta app será python -m gunicorn wsgi:app.

3. Configurando Host, Puerto y Workers para Square

Para que el contenedor de Square pueda recibir el tráfico de internet y distribuirlo a tu app, debes obligatoriamente apuntar el servidor al host 0.0.0.0 y al puerto 80.

El comando de inicio ideal queda así:

python -m gunicorn --bind 0.0.0.0:80 --workers 3 wsgi:app

¿Qué hace cada parámetro aquí?

• --bind 0.0.0.0:80 (o -b): Vincula Gunicorn a todas las interfaces de red del contenedor en el puerto HTTP por defecto (80), permitiendo que Square entregue las solicitudes externas directamente a tu app.
• --workers 3 (o -w): Define la cantidad de procesos de trabajo simultáneos.

💡 Consejo de Oro para Square: El número de workers depende del plan de tu contenedor. La recomendación por defecto de Gunicorn es (2 × número de núcleos de CPU) + 1. Si tu plan en Square ofrece 1 núcleo de CPU, configúralo con 3 workers para obtener la máxima concurrencia sin superar el límite de memoria.

4. Automatizando el Inicio en squarecloud.app

Para que todo esto funcione de forma 100% automatizada, solo necesitas mapear el comando de inicio dentro del archivo de configuración de Square, el squarecloud.app (o squarecloud.toml), ubicado en la raíz de tu proyecto.

Añade la directiva START apuntando al comando que estructuramos:

MAIN=wsgi.py
MEMORY=512
VERSION=recommended
START=python -m gunicorn --bind 0.0.0.0:80 --workers 3 wsgi:app

Si prefieres usar un archivo de configuración separado para Gunicorn (como un gunicorn.conf.py para reglas de timeout o logs más avanzados), puedes simplificar la línea de inicio:

START=python -m gunicorn -c gunicorn.conf.py wsgi:app

(Recordando que, dentro de tu gunicorn.conf.py, la variable bind debe ser obligatoriamente "0.0.0.0:80").

Actualizado el: 03/07/2026