🔀 Merge branch 'fix-45' into 'develop'

📝 — Document better how to deploy with gunicorn (fix #45)

See merge request framasoft/framaspace/argos!53

docs/installation/getting-started.md

@@ -14,12 +14,19 @@ pip install argos-monitoring
 ```
 
 You may want to install Argos in a virtualenv:
+
 ```bash
 python3 -m venv venv
 source venv/bin/activate
 pip install argos-monitoring
 ```
 
+For production, we recommend the use of [Gunicorn](https://gunicorn.org/), which you can install at the same time as Argos:
+
+```bash
+pip install argos-monitoring[gunicorn]
+```
+
 ## Install from sources
 
 Once you got the source locally, create a virtualenv and install the dependencies:
@@ -78,7 +85,41 @@ Then you can start the server:
 argos server start
 ```
 
-The server reads the `yaml` file at startup, and populates the tasks queue with the checks defined in the configuration. 
+The server reads the `yaml` file at startup, and populates the tasks queue with the checks defined in the configuration.
+
+This way to start the server is not suitable for production, use it only for developing or testing.
+
+## Starting the server for production
+
+For production, you can use [Gunicorn](https://gunicorn.org/) to start the server.
+
+To install Gunicorn in the virtualenv, if you didn’t already install Argos that way:
+
+```bash
+pip install argos-monitoring[gunicorn]
+```
+
+To start the server:
+
+```bash
+gunicorn "argos.server.main:get_application()" -k uvicorn.workers.UvicornWorker
+```
+
+There is some gunicorn’s options that you should use:
+- `-w INT, --workers INT`: the number of worker processes for handling requests. Default is `1`.
+- `-b ADDRESS, --bind ADDRESS`: the socket to bind. Default is `127.0.0.1:8000`.
+- `--forwarded-allow-ips STRING`: front-end's IPs from which allowed to handle set secure headers as a comma-separated list. Default is `127.0.0.1`.
+
+So, to start the server with 4 workers while listening to `127.0.0.1:8001`:
+
+```bash
+gunicorn "argos.server.main:get_application()" -k uvicorn.workers.UvicornWorker -w 4 -b 127.0.0.1:8001
+```
+
+Gunicorn has a lot of other options, have a look at `gunicorn --help`.
+
+Argos uses FastAPI, so you can use other ways to start the server.
+See <https://fastapi.tiangolo.com/deployment/manually/#asgi-servers> (but Gunicorn is recommended).
 
 ## Generating a token 
 

docs/installation/tl-dr.md

@@ -13,7 +13,7 @@ cd /tmp/argos
 python3 -m venv venv
 source venv/bin/activate
 pip install argos-monitoring
-argos server generate-config > config.yaml
+argos server generate-config > argos-config.yaml
 argos server migrate
 argos server generate-token
 ```
@@ -50,10 +50,11 @@ adduser --home /opt/argos --disabled-login --disabled-password --system argos
 cd /opt/argos
 python3 -m venv venv
 chown argos: -R venv
-sudo -u argos bash -c "source venv/bin/activate && pip install argos-monitoring"
+sudo -u argos bash -c "source venv/bin/activate && pip install argos-monitoring[gunicorn]"
 
 mkdir /etc/argos
-wget https://framagit.org/framasoft/framaspace/argos/-/raw/main/conf/config-example.yaml -O /etc/argos/config.yaml
+/opt/argos/venv/bin/argos server generate-config > /etc/argos/config.yaml
+
 cat <<EOF > /etc/default/argos-server
 ARGOS_YAML_FILE="/etc/argos/config.yaml"
 ARGOS_DATABASE_URL="postgresql://argos:THE_DB_PASSWORD@localhost/argos"

pyproject.toml

@@ -24,7 +24,6 @@ dependencies = [
   "alembic>=1.13.0,<1.14",
   "click>=8.1,<9",
   "fastapi>=0.103,<0.104",
-  "gunicorn>=21.2,<22",
   "httpx>=0.25,<1",
   "Jinja2>=3.0,<4",
   "psycopg2-binary>=2.9,<3",
@@ -62,6 +61,9 @@ docs = [
   "sphinx>=7,<8",
   "sphinxcontrib-mermaid>=0.9,<1",
 ]
+gunicorn = [
+  "gunicorn>=21.2,<22",
+]
 
 [project.urls]
 homepage = "https://framasoft.frama.io/framaspace/argos/"