> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.squarecloud.app/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Gunicorn: Production webserver for WSGI applications

# How to Configure Gunicorn in Production on Square Cloud

If you have been developing web applications with Python using frameworks like Django or Flask, you know that running the built-in development server (`flask run` or `python app.py`) is not an option for the real world. They cannot handle the load of multiple simultaneous requests.

To deploy your application with performance and stability, you need a battle-tested WSGI server: **Gunicorn** (Green Unicorn). 

Below, see how to orchestrate Gunicorn perfectly within the Square Cloud environment, which already handles the `0.0.0.0` host and the default port `80` for you.

---

## 1. Declaring Dependencies

Since Square handles the installation for you automatically, your only job is to ensure that Gunicorn is listed as a project dependency.

If you use **`requirements.txt`**, add the line:
```text
gunicorn
```

If your project uses the official **`pyproject.toml`** standard (PEP 621), add it to the project dependencies section:
```toml
[project]
dependencies = [
    "gunicorn>=23.0.0",
]
```

When uploading the project, Square will read these files and leave the Gunicorn module ready for use.

---

## 2. Understanding the Command

To ensure that Gunicorn is executed exactly by the isolated Python interpreter of your container on Square, the best practice is to call it as a module using the `-m` flag:

```bash
python -m gunicorn [options] module_name:application_attribute
```

* **`module_name`**: The name of the `.py` file where your application is located (e.g., `main` or `wsgi`).
* **`application_attribute`**: The variable that receives the instance of your framework (usually called `app` or `application`).

### Practical Example with Flask
If you have a file in the root directory named `wsgi.py`:

```python
from my_project import app

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

The command for Gunicorn to manage this app will be `python -m gunicorn wsgi:app`.

---

## 3. Configuring Host, Port, and Workers for Square

For the Square container to receive internet traffic and distribute it to your app, you must bind the server to the `0.0.0.0` host and port `80`.

The ideal startup command looks like this:

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

### What does each parameter do here?
* **`--bind 0.0.0.0:80` (or `-b`)**: Binds Gunicorn to all network interfaces of the container on the default HTTP port (`80`), allowing Square to deliver external requests directly to your app.
* **`--workers 3` (or `-w`)**: Defines the number of simultaneous worker processes. 

> 💡 **Pro-Tip for Square:** The number of workers depends on your container's plan. Gunicorn's default recommendation is `(2 × number of CPU cores) + 1`. If your Square plan provides 1 CPU core, configure it to `3` workers to extract maximum concurrency without exceeding the memory limit.

---

## 4. Automating the Startup in `squarecloud.app`

To make all of this work 100% automatically, you just need to map the startup command inside Square's configuration file, `squarecloud.app`, located at the root of your project.

Add the `START` directive pointing to the command we structured:

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

If you prefer to use a separate configuration file for Gunicorn (such as a `gunicorn.conf.py` for advanced timeout rules or logging), you can simplify the startup line:

```ini
START=python -m gunicorn -c gunicorn.conf.py wsgi:app
```
*(Remember that inside your* *`gunicorn.conf.py`**, the `bind` variable must strictly be `"0.0.0.0:80"`).*