Skip to content

Environment Variables

This page contains all available environment variables supported by Mathesar. See the specific installation guides for the applicable environment variables and instructions on how to set them.

Backend configuration

SECRET_KEY

  • Description: A unique random string used by Django for cryptographic signing (see Django docs). It helps Mathesar secure user sessions and encrypt saved PostgreSQL passwords.
  • Format: A 50 character string

  • Additional information:

    To generate a secret key you can use this browser-based generator or run this command on MacOS or Linux:

    echo $(cat /dev/urandom | LC_CTYPE=C tr -dc 'a-zA-Z0-9' | head -c 50)

ALLOWED_HOSTS

  • Description: A set of strings representing the host/domain names that Django is allowed to serve. This is a security measure to prevent HTTP Host header attacks (see Django docs).
  • Format: A set of host/domain names separated by a comma
  • Default value: .localhost,127.0.0.1,[::1]

Internal database configuration

Default values below are from our docker-compose.yml file, used if installing via Docker Compose.

The database specified in this section is used to store Mathesar’s internal data. If desired, it can also be connected to Mathesar’s UI to store user data.

POSTGRES_DB

  • Description: Specifies a name for the database that will be created and used by Mathesar for managing internal data.
  • Default value: mathesar_django

POSTGRES_USER

  • Description: Specifies creation of a user with superuser privileges and a database with the same name.
  • Default value: mathesar

POSTGRES_PASSWORD (optional)

  • Description: Specifies the superuser password that is required to be set for the PostgreSQL docker image.
  • Default value: mathesar

POSTGRES_HOST

  • Description: Specifies the host name on which portgres listen for connections from client applications.
  • Default value: mathesar_db
    • When installing via docker, this value can reference:
      • A Docker service name (e.g., mathesar_django)
      • A TCP host address (e.g., host.docker.internal)
      • A Unix socket path (e.g., /var/run/postgresql)

POSTGRES_PORT (optional)

  • Description: Specifies the port on which portgres listen for connections from client applications.
  • Default value: 5432

Caddy reverse proxy configuration

OPTIONAL

Only needed if you’re using the Caddy configuration in our default Docker Compose file.

DOMAIN_NAME

  • Description: The public URL that will be used to access Mathesar (see Caddy docs).

  • Format: A URL or hostname

    Example values

    • https://example.com
    • localhost
    • http://localhost

  • Additional information

    • If the protocol is http, then Caddy will serve traffic via HTTP only.
    • If the protocol is https or is not specified, then Caddy will serve traffic via HTTPS (and will redirect all HTTP traffic to HTTPS). In this case Caddy will also attempt to automatically set up HTTPS with Let’s Encrypt for you (see Caddy docs).

    Tip

    • Set this to localhost if you’d like Mathesar to be available only on localhost
    • Set the protocol to http if you don’t want Caddy to automatically handle setting up SSL, e.g. http://example.com

Single sign-on (SSO) configuration

OPTIONAL

Only used if using SSO in installations where the local filesystem is inaccessible.

OIDC_CONFIG_DICT (optional)

  • Description: The configuration for enabling SSO and configuring providers in Mathesar.

  • Format: A stringified JSON representation of the config in the sso.yml file.

    Example

     OIDC_CONFIG_DICT="{\"version\": 1,\"oidc_providers\": {\"provider1\": {\"provider_name\": \"okta\",\"client_id\": \"client-id\",\"secret\": \"client-secret\",\"server_url\": \"https://trial-2872264-admin.okta.com\"}}}"

  • Additional information: The following tools might help you convert the YAML syntax from sso.yml into the proper format: