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, while Dev provides defaults for many of them.

Each setting reads an environment variable named <PREFIX>_<SETTING>. The prefix is DJANGO for standard Django settings (e.g. DJANGO_SECRET_KEY) and GEORAMA for Georama settings (e.g. GEORAMA_DB_NAME).

Environment Files¶

Required Variables¶

Django¶

DJANGO_CONFIGURATION

Selects the configuration class (Dev or Prod).

• Dev: Dev. 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 development, 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 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:8000/export, no need to put it in .env.
• Prod: required. Use the full endpoint, including the /export path, e.g. http://qsl-exporter:8000/export.

QSL_REDIS_URL

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

• Dev: defaults to redis://qsl-redis:6379, also set by compose.yml.
• 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: defaults to http://localhost:9308, the geogirafe compose service.
• Prod: required, e.g. https://map.example.com.

GEORAMA_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: defaults to tests/resources/projects, which is also mounted as /io/data in 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 development it reaches the qsl and qsl-exporter services through the shared .env. In production, set it on the QSL containers.

Docker Compose (Development Only)¶

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

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
GEORAMA_CORS_ALLOWED_ORIGINS=https://map.example.com

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