Open Forms can be ran both as a Docker container or directly on a VPS or dedicated server. It depends on other services, such as database and cache backends, which can be configured through environment variables.
You also need to expose Open Forms through a web server acting as a reverse proxy, such as nginx or your ingress solution on Kubernetes. See the :ref:`installation_config_webserver` section for some configuration recommendations.
.. seealso:: * :ref:`installation_security`
DJANGO_SETTINGS_MODULE
: which environment settings to use. Available options:openforms.conf.docker
openforms.conf.dev
openforms.conf.ci
SECRET_KEY
: secret key that's used for certain cryptographic utilities. You should generate one via miniwebtoolALLOWED_HOSTS
: A comma separated (without spaces!) list of domains that serve the installation. Used to protect againstHost
header attacks. Defaults to*
for thedocker
environment and defaults to127.0.0.1,localhost
for thedev
environment.BASE_URL
: The absolute base URL where the Open Forms (backend) is (publicly) accessible. The format must behttp[s]://<hostname>[:<optional-port>]/[optional-path]
. This URL is used in various security mechanisms, in tooling to construct fully qualified absolute URLs (outside of regular HTTP requests) and serves as input for automatic configuration aspects such as the analytics configuration.
DB_HOST
: Hostname of the PostgreSQL database. Defaults todb
for thedocker
environment, otherwise defaults tolocalhost
.DB_USER
: Username of the database user. Defaults toopenforms
,DB_PASSWORD
: Password of the database user. Defaults toopenforms
,DB_NAME
: Name of the PostgreSQL database. Defaults toopenforms
,DB_PORT
: Port number of the database. Defaults to5432
.CELERY_BROKER_URL
: URL for the Redis task broker for Celery. Defaults toredis://127.0.0.1:6379/1
.CELERY_RESULT_BACKEND
: URL for the Redis result broker for Celery. Defaults toredis://127.0.0.1:6379/1
.
EMAIL_HOST
: Email server host. Defaults tolocalhost
.EMAIL_PORT
: Email server port. Defaults to25
.EMAIL_HOST_USER
: Email server username. Defaults to""
.EMAIL_HOST_PASSWORD
: Email server password. Defaults to""
.EMAIL_USE_TLS
: Indicates whether the email server uses TLS. Defaults toFalse
.DEFAULT_FROM_EMAIL
: The email address to use a default sender. Defaults toopenforms@example.com
.
See: https://github.com/adamchainz/django-cors-headers
CORS_ALLOWED_ORIGINS
: A list of origins that are authorized to make cross-site HTTP requests. Defaults to[]
. An example value would be:https://cms.example.org,https://forms.example.org
CSRF_TRUSTED_ORIGINS
: the list of trusted CSRF origins, e.g.cms.example.com
. When embedding forms on third party sites, these third party domains need to be added to the allowlist. The default value is taken from theCORS_ALLOWED_ORIGINS
setting. See also the Django documentation.
It is recommended to configure CORS explicitly by setting just CORS_ALLOWED_ORIGINS
.
Other CORS-settings
The settings below are available but should only be specified/used when you have
intricate knowledge of how they are used. While wildcards and regexes may seem
attractive options, we are currently limited by our framework in how
CSRF_TRUSTED_ORIGINS
can be specified (which must be an explicit list without
patterns or wildcards).
CORS_ALLOW_ALL_ORIGINS
: IfTrue
, all origins will be allowed. Other settings restricting allowed origins will be ignored.Defaults toFalse
.CORS_ALLOWED_ORIGIN_REGEXES
: A list of strings representing regexes that match Origins that are authorized to make cross-site HTTP requests. Defaults to[]
.CORS_EXTRA_ALLOW_HEADERS
: The list of non-standard HTTP headers that can be used when making the actual request. These headers are added to the internal settingCORS_ALLOW_HEADERS
. Defaults to[]
.
CSP_REPORT_ONLY
: ifTrue
, CSP only reports violations but does not block them. Defaults toFalse
, meaning the CSP is enforced.CSP_REPORTS_SAVE
: whether to save violation reports to the database. Defaults toFalse
.CSP_REPORTS_LOG
: whether to log violation reports. In containerized environments this will be logged tostdout
, otherwise to file. If monitoring (Sentry) is set up, reports will also be visible there through logging. Defaults toTrue
.CSP_REPORT_PERCENTAGE
: float between 0 and 1.0, expressing the percentage of violations that will be reported. Defaults to1.0
(100%).CSP_EXTRA_DEFAULT_SRC
: A comma separated list of extradefault-src
directives. Defaults to empty list.CSP_EXTRA_IMG_SRC
: A comma separated list of extraimg-src
directives. Defaults to empty list.
See also the :ref:`developer documentation <developers_csp>` and https://django-csp.readthedocs.io/en/latest/ for more information on CSP.
SENTRY_DSN
: URL of the sentry project to send error reports to. Defaults to an empty string (i.e. no monitoring). See Sentry settings.SDK_SENTRY_DSN
: URL of the sentry project for the SDK to send error reports to. Defaults to an empty string (i.e. no monitoring). This is a public Sentry DSN. See Sentry settings.SDK_SENTRY_ENVIRONMENT
: the environment label for the SDK to group events. Defaults toENVIRONMENT
.ELASTIC_APM_SERVER_URL
: Server URL of Elastic APM. Defaults toNone
. If not set, Elastic APM will be disabled by setting internal settingELASTIC_APM["ENABLED"]
toFalse
andELASTIC_APM["SERVER_URL"]
tohttp://localhost:8200
. See Elastic settings.ELASTIC_APM_SECRET_TOKEN
: Token for Elastic APM. Defaults todefault
. See Elastic settings.LOG_STD_OUT
: Write all log entries tostdout
instead of log files. Defaults toTrue
when using Docker and otherwiseFalse
.
Submissions are :ref:`processed <developers_backend_core_submissions>` in the background after the end-user has submitted the form data. This can fail because of external factors, and Open Forms has an automatic-retry mechanism.
The following settings allow you to tweak the parameters of this mechanism.
RETRY_SUBMISSIONS_INTERVAL
: the interval (in seconds) of retrying. Defaults to every 300s (5 min).RETRY_SUBMISSIONS_TIME_LIMIT
: the time limit from when the submission was submitted that automatic retries will continue. After this time limit has elapsed, there are no automatic retries anymore, but manual retries are still available. Defaults to48
hours.
MAX_FILE_UPLOAD_SIZE
: configure the maximum allowed file upload size. See :ref:`installation_file_uploads` for more details. The default is50M
.DEBUG
: Used for more traceback information on development environment. Various other security settings are derived from this setting! Defaults toTrue
for thedev
environment, otherwise defaults toFalse
.IS_HTTPS
: Used to construct absolute URLs and controls a variety of security settings. Defaults to the inverse ofDEBUG
.Warning
We strongly recommended setting IS_HTTPS=False in local dev environments only. Deploying over HTTP instead of HTTPS makes you prone to man-in-the-middle attacks. Any instance reachable from other computers should only be deployed with HTTPS.
The value of
IS_HTTPS
is used for the default values of:LANGUAGE_COOKIE_SECURE
LANGUAGE_COOKIE_SAMESITE
SESSION_COOKIE_SECURE
SESSION_COOKIE_SAMESITE
CSRF_COOKIE_SECURE
CSRF_COOKIE_SAMESITE
The idea is that any cookies automatically receive the
Secure
attribute when we're known to be in an HTTPS context. For non-HTTPS contexts this is disabled as it would otherwise break the application's functionality.Similarly, the
SameSite
attribute controls how cookies are restricted to domains other than the domain where the backend is deployed. In an HTTPS context it is set toNone
, in an HTTP context it is set toLax
by default.USE_X_FORWARDED_HOST
: whether to grab the domain/host from theX-Forwarded-Host
request header or not. This header is typically set by reverse proxies (such as nginx, traefik, Apache...). DefaultFalse
- this is a header that can be spoofed and you need to ensure you control it before enabling this.DB_ENGINE
: Backend to use as database system. See Django DATABASE settings for a full list of backends. Only the default is supported but others might work. Defaults todjango.db.backends.postgresql
CACHE_DEFAULT
: The default Redis cache location. Defaults tolocalhost:6379/0
.CACHE_AXES
: The Redis cache location for Axes (used to prevent brute force attacks). Defaults tolocalhost:6379/0
.CACHE_OIDC
: The Redis cache location for the OIDC configuration. Defaults tolocalhost:6379/0
.ENVIRONMENT
: Short string to indicate the environment (test, production, etc.) Defaults to""
.GIT_SHA
: The Git commit hash belonging to the code running the instance. Defaults to the automatically determined commit hash, if the application is run from a checked out Git repository.RELEASE
: The version of the application. If not provided, theGIT_SHA
is used.SDK_RELEASE
: The version of the SDK bundled. By default, this is sourced from the.sdk-release
file and should only be overridden if you're doing things in custom Docker images. The value is used to know which SDK JS/CSS files to include on the form detail page.SESSION_EXPIRE_AT_BROWSER_CLOSE
: Controls if sessions expire at browser close. This applies to both the session of end-users filling out forms and staff using the administrative interface. Enabling this forces users to log in every time they open their browser. Defaults toFalse
.EXTRA_VERIFY_CERTS
: A comma-separated list of paths to certificates to trust, empty by default. If you're using self-signed certificates for the services that Open Forms communicates with, specify the path to those (root) certificates here, rather than disabling SSL certificate verification. Example:EXTRA_VERIFY_CERTS=/etc/ssl/root1.crt,/etc/ssl/root2.crt
.SELF_CERTIFI_DIR
: Temporary directory where the generated bundle ofEXTRA_VERIFY_CERTS
will be stored.CACHE_PORTALOCKER
: Redis URL for file locks. Defaults tolocalhost:6379/0
.DEFAULT_TIMEOUT_REQUESTS
: The default timeout duration (in seconds) when calling external APIs/services. Defaults to10.0
. Requests taking longer than this duration are aborted and errors bubble up. Specific calls may use an explicitly provided timeout, which is not affected by this setting.CURL_CA_BUNDLE
: If this variable is set to an empty string, it disables SSL/TLS certificate verification. More information about why can be found on this stackoverflow post. Even calls from Open Forms to any other service will be disabled, so this variable should be used with care to prevent unwanted side-effects.BEAT_SEND_EMAIL_INTERVAL
: the interval (in seconds) of sending queued e-mails, defaults to20
.SUBMISSION_REPORT_URL_TOKEN_TIMEOUT_DAYS
: Configure how many days the URL to the submission report is usable.TEMPORARY_UPLOADS_REMOVED_AFTER_DAYS
: Configure how many days before unclaimed temporary uploads are removed.OPENFORMS_LOCATION_CLIENT
: The client to be used for auto filling a street name and city when given a postcode and house number. Defaults to our internal BAG configuration.ENABLE_THROTTLING
: Enable or disable request throttling (to protect against (D)DOS, for example). Default enabled.THROTTLE_RATE_ANON
: Default throttle rate for anonymous users (this includes the end-users filling out (embedded) forms using the SDK!). Defaults to2500/hour
. Note that if throttling is disabled altogether, this configuration parameter has no effect.THROTTLE_RATE_USER
: Default throttle rate for authenticated users (typicall users logged in to the admin interface). Defaults to15000/hour
. Note that if throttling is disabled altogether, this configuration parameter has no effect.THROTTLE_RATE_POLLING
: Throttle rate for endpoints that are polled frequently. If you're authenticated as staff user, the throttling is bypassed completely. Defaults to50000/hour
. Note that if throttling is disabled altogether, this configuration parameter has no effect.NUM_PROXIES
: The number of application proxies that the API runs behind. See the upstream documentation for more context. Defaults to1
.TWO_FACTOR_FORCE_OTP_ADMIN
: Enforce 2 Factor Authentication in the admin or not. DefaultTrue
. You'll probably want to disable this when using OIDC.TWO_FACTOR_PATCH_ADMIN
: Whether to use the 2 Factor Authentication login flow for the admin or not. DefaultTrue
. You'll probably want to disable this when using OIDC.FORMS_EXPORT_REMOVED_AFTER_DAYS
: The number of days after which zip files of exported forms should be deleted. Defaults to 7 days.SUBPATH
: A string with a prefix for all URL paths, for example/openforms
. Typically used at the infrastructure level to route to a particular application on the same (sub)domain. Defaults to empty string meaning that Open Forms is hosted at the root (/
).
There are two strategies to specify the environment variables:
- provide them in a
.env
file - start the component processes (with uwsgi/gunicorn/celery) in a process manager that defines the environment variables
This is the most simple setup and easiest to debug. The .env
file must be
at the root of the project - i.e. on the same level as the src
directory (
NOT in the src
directory).
The syntax is key-value:
SOME_VAR=some_value OTHER_VAR="quoted_value"
If you use a process manager (such as supervisor/systemd), use their techniques to define the envvars. The component will pick them up out of the box.