Environment Variables¶

Georama is configured through environment variables. This page lists them, first the required ones and then the optional ones, and explains what each one does in development and in production.

How the Configuration Works¶

The Django settings (src/georama/settings.py) are built with django-configurations. They define several configuration classes, and DJANGO_CONFIGURATION selects which one is active:

Base holds the restrictive defaults shared by all configurations, so most values have to be set explicitly in production. Dev provides defaults for the values which are the same on every developer machine (e.g. allowed hosts and origins), the values which depend on the services of the stack (e.g. the QSL and database addresses) are set by compose.yml.

Each setting reads an environment variable named <PREFIX>_<SETTING>. The prefix is DJANGO for settings of Django and Django apps (e.g. DJANGO_SECRET_KEY, DJANGO_CORS_ALLOWED_ORIGINS for django-cors-headers) and GEORAMA for Georama settings (e.g. GEORAMA_DB_NAME). Settings shared with other applications are read without prefix (e.g. QSL_REDIS_URL, also read by QSL).

Environment Files¶

Docker Compose only passes the variables to the containers which the compose files reference. The values of the stack (e.g. GEORAMA_QSL_EXPORTER_URL) are set directly in compose.yml, .env provides the secrets and the variant specific values. For production, see the example below.

Required Variables¶

Django¶

DJANGO_CONFIGURATION

Selects the configuration class (Dev or Prod).

• Dev: Dev, set by compose.dev.yml (compose.yml sets Prod for the prod like stack). Outside of the stack set it explicitly: the ASGI server defaults to Dev, but the manage command defaults to Prod, so uv run manage … would fail without it. The create_dev_content_* commands also only run when it is Dev.
• Prod: Prod. Mandatory: the production image starts Gunicorn on the ASGI application, which falls back to Dev (with DEBUG enabled) when this variable is missing.

DJANGO_SECRET_KEY

Django's SECRET_KEY, used for signing sessions, CSRF tokens, password reset links, etc.

• Dev: ignored, Dev uses a hard-coded insecure key.
• Prod: required and must not be empty. Use a long random value and keep it secret, e.g. generated with python -c "import secrets; print(secrets.token_urlsafe(64))".

DJANGO_ALLOWED_HOSTS

Host names Georama answers to (ALLOWED_HOSTS), space separated. A leading dot matches all subdomains, e.g. .georama.example.com.

• Dev: not needed, defaults to .localhost georama.local.
• Prod: required in practice, e.g. .georama.example.com.

Set it in production, including the subdomains

Georama starts without this variable, but the list is then empty and, as DEBUG is off, Django answers every request with a 400 Bad Request.

Organisations are served on subdomains of GEORAMA_ORGANISATION_DOMAIN (e.g. acme.georama.example.com), and the host is checked before the organisation is resolved: use a leading dot (.georama.example.com) so that they are accepted too.

DJANGO_CSRF_TRUSTED_ORIGINS

Origins trusted for unsafe requests (POST, PUT, …) (CSRF_TRUSTED_ORIGINS), space separated, with scheme, e.g. https://georama.example.com.

• Dev: optional, defaults to the local Georama and GeoGirafe addresses (http://localhost:4242, http://localhost:9308, https://localhost:9309, …).
• Prod: required (may be empty, but then cross-origin forms are rejected).

Database¶

The connection to the PostgreSQL / PostGIS database. In the stack, compose.yml also uses GEORAMA_DB_USER, GEORAMA_DB_PW and GEORAMA_DB_NAME to initialise the georama-db service, and refuses to start if they (or GEORAMA_DB_OPTIONS) are missing.

QGIS-Server-Light¶

GEORAMA_QSL_EXPORTER_URL

Full URL of the QSL exporter endpoint. Georama POSTs the path of a QGIS project to it when a project is imported, and receives the project description back.

• Dev: set by compose.yml to http://qsl-exporter:5000/export, no need to put it in .env.
• Prod: required. Use the full endpoint, including the /export path, e.g. http://qsl-exporter:5000/export.

QSL_REDIS_URL

URL of the Redis instance used as job queue between Georama and the QSL rendering workers (qsl-worker). Note that this variable has no GEORAMA_ prefix: it is shared with QSL, which reads the same name.

• Dev: set by compose.yml to redis://qsl-redis:6379, for Georama and the QSL workers.
• Prod: required, e.g. redis://qsl-redis:6379. It must point to the same Redis as the QSL workers.

Georama¶

GEORAMA_ORGANISATION_DOMAIN

The domain Georama runs on. The organisation middleware compares the requested host with it to find the organisation: a request to <org>.georama.example.com is served for the organisation whose domain is <org>, a request to the domain itself is served for the global organisation. If Georama already runs under a subdomain, include it, e.g. sub.example.com.

• Dev: ignored, hard-coded to localhost (use <org>.localhost:4242).
• Prod: required.

GEORAMA_WEBGISURL

Public URL of the GeoGirafe viewer. It is used for the link on the home page, to build the theme URLs, and to validate URLs given to the WebGIS API (they must start with it).

• Dev: set by compose.yml to https://localhost:9309, the geogirafe compose service.
• Prod: required, e.g. https://map.example.com.

DJANGO_CORS_ALLOWED_ORIGINS

Origins allowed to call the API from a browser (django-cors-headers), space separated. Typically the GeoGirafe URL.

• Dev: optional, defaults to the local GeoGirafe addresses.
• Prod: required (may be empty, but then browsers block cross-origin calls, e.g. from GeoGirafe).

GEORAMA_DATA_INTEGRATION_ROOT

Directory containing the QGIS projects and their data, with one sub-folder per organisation (the global organisation folder is created at startup). QSL must see the same files.

• Dev: set by compose.yml to /io/data, where LOCAL_PROJECTS (default ./tests/resources/projects) is mounted in Georama and the QSL services.
• Prod: required, but already set to /io by the production image: mount your projects volume there, or override the variable.

Optional Variables¶

Georama¶

Database Tuning¶

Security and CORS¶

Authentication with OpenID Connect¶

Georama can delegate the login to an OpenID Connect provider (e.g. Keycloak) through django-allauth.

QGIS-Server-Light¶

QSL_LOG_LEVEL

Log level of the QSL services (debug, info, …). Georama does not read it: in the stack, compose.yml passes it to the qsl-worker and qsl-exporter services (default info, debug for the worker of compose.dev_with_qsl.yml). In production, set it on the QSL containers.

Docker Compose¶

These variables are only used by Docker Compose, when building the images or starting the stack. They have no effect on the production image itself.

Summary: Dev vs Prod¶

Production Example¶

DJANGO_CONFIGURATION=Prod
DJANGO_SECRET_KEY=<long-random-secret>
DJANGO_ALLOWED_HOSTS=.georama.example.com
DJANGO_CSRF_TRUSTED_ORIGINS=https://georama.example.com https://map.example.com
DJANGO_SECURE_PROXY_SSL_HEADER=HTTP_X_FORWARDED_PROTO,https

GEORAMA_DB_NAME=georama
GEORAMA_DB_USER=georama
GEORAMA_DB_PW=<strong-password>
GEORAMA_DB_HOST=db.example.com
GEORAMA_DB_PORT=5432

GEORAMA_ORGANISATION_DOMAIN=georama.example.com
GEORAMA_WEBGISURL=https://map.example.com
DJANGO_CORS_ALLOWED_ORIGINS=https://map.example.com

GEORAMA_QSL_EXPORTER_URL=http://qsl-exporter:5000/export
QSL_REDIS_URL=redis://qsl-redis:6379