[DOC] Backend servers configuration

INSTALL.md

@@ -95,6 +95,80 @@ To run Gargantext backend servers do:
     pipenv run make start
 
 
+## Configuration
+
+Configuration is located in three files: `.env` (environment variables),
+`gargantext.ini` and `postgrest.conf` (these file names are default values,
+they can be specified in `GARGANTEXT_CONF` and `POSTGREST_CONF` env variables).
+
+These files are automatically generated by running `make` (or
+`make ENVIR=prod`), which takes care of the tedious work.
+
+To generate configuration again, one can run `./tools/mkconf.sh -f <target>`
+where `<target>` can be `dev` or `prod`. Be careful, this script will change
+Django secret key and PostgREST role password, so all current tokens and
+sessions will be invalidated.
+
+### Environment variables
+
+Configured in `.env` (loaded by `pipenv` when running `pipenv run` or
+`pipenv shell`).
+
+* `DJANGO_SETTINGS_MODULE`: python file path of the django settings module
+* `GARGANTEXT_CONF`: django backend and uwsgi configuration file path
+* `POSTGREST_CONF`: postgrest configuration file path
+
+### Django backend
+
+Configured in `GARGANTEXT_CONF` (`gargantext.ini` by default) under `[django]`
+section. You can override options listed below with environment variables. For
+example, to start production servers with DEBUG mode disabled from a
+development environment, you can do: `DEBUG=False make ENVIR=prod start`.
+
+See `settings.py` (full path in `DJANGO_SETTINGS_MODULE`) to understand details
+about how these options are used.
+
+* `DEBUG`: `True` | `False`
+* `SECRET_KEY`: arbitrary string used by django in various ways[^1], and to
+  generate JSON Web Tokens, so it MUST be reflected in PostgREST configuration
+* `ALLOWED_HOSTS`: space separated list of allowed hosts
+* `TIME_ZONE`: see <https://en.wikipedia.org/wiki/List_of_tz_database_time_zones>
+* `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASS`: pretty obvious...
+* `LOG_FILE`: log file path
+* `LOG_LEVEL`: `DEBUG` | `INFO` | `WARNING` | `ERROR` | `CRITICAL`
+* `LOG_FORMATTER`: `simple` | `verbose`, formatters can be added in settings.py
+* `TESTSERVER_PIDFILE`: pidfile for the testserver (only used by startup script)
+
+[^1]: Details here: <https://stackoverflow.com/questions/15170637/effects-of-changing-djangos-secret-key#answer-15383766>.
+
+### uWSGI
+
+Configured in `GARGANTEXT_CONF` (`gargantext.ini` by default) under `[uwsgi]`
+section.
+
+uWSGI (used to serve django backend in production) configuration is not very
+well documented. Here is a comprehensive but very harsh reference of all its
+options: <https://uwsgi-docs.readthedocs.io/en/latest/Options.html>.
+
+Here are some general options you may need to change:
+
+* `daemonize`: log file path
+* `log-reopen`: a `true` value tells uWSGI to write a new file each day
+* `pidfile`: pidfile of master process
+
+### PostgREST
+
+Configured in `POSTGREST_CONF` (`postgrest.conf` by default).
+
+Here are Gargantext specific options used by our startup script (NB: these
+options won't be taken into account by postgrest itself):
+
+* `pidfile`: pidfile of postgrest process
+* `logfile`: log file path
+
+For general options, see <https://postgrest.com/en/v4.3/install.html#configuration>.
+
+
 ## Customize dev environment
 
 To install specific packages without messing with dependencies, just use pip.