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. If not set as an environment variable, Mathesar will generate one at random, and persist that on disk. The variable only needs to be set for backwards compatibility, or in deployments where persistence of secret information on disk is not possible.
  • Format: A 50 character string
  • Additional information: You may use the button below to generate a key, and automatically copy it. Remember: do not share this key with anyone.

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]

WEB_CONCURRENCY

  • Description: Sets the number of sync Gunicorn workers, affecting the number of concurrent requests Mathesar can handle. Bigger is better, subject to system resources. The typically-recommended number is 2 * $(NUM_PROC) + 1, where NUM_PROC is the number of logical cores on your machine. So, if Mathesar is running on a server with 4 vCPUs, then this should be set to 9.
  • Format: An integer.
  • Default value: 3

MATHESAR_DJANGO_ADMIN_ENABLED

  • Description: Enables Django’s built-in admin interface at /admin/. This is disabled by default and does not affect Mathesar’s own administration pages under /administration/.
  • Format: true or false
  • Default value: false
  • Additional information: If you enable this after installing Mathesar directly on Linux, macOS, or WSL, start Mathesar once with mathesar run --setup-django so Django can apply any required admin migrations and collect admin static files.

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

POSTGRES_SSLMODE (optional)

  • Description: Specifies the SSL mode for connecting to the internal PostgreSQL database. Controls whether and how SSL encryption is used for the connection.
  • Format: One of disable, prefer, or require
  • Default value: prefer

  • Additional information:

    • disable: Do not use SSL.
    • prefer: Use SSL if the server supports it, otherwise connect without SSL.
    • require: Always use SSL, but do not verify the server certificate.

    Note

    PostgreSQL also supports verify-ca and verify-full modes for certificate verification, but Mathesar does not currently support these. If you need certificate verification, please open an issue to let us know.

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.

SSO_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. Both schema version 1 (OIDC only) and version 2 (OIDC + GitHub) are accepted.

    Version 2 (OIDC + GitHub)

     SSO_CONFIG_DICT="{\"version\": 2,\"providers\": {\"provider1\": {\"type\": \"oidc\",\"provider_name\": \"okta\",\"client_id\": \"client-id\",\"secret\": \"client-secret\",\"server_url\": \"https://trial-2872264-admin.okta.com\"},\"provider2\": {\"type\": \"github\",\"client_id\": \"github-client-id\",\"secret\": \"github-client-secret\"}}}"

    Version 1 (OIDC only, legacy)

     SSO_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:

OIDC_CONFIG_DICT (optional, alias)

  • Description: A backwards-compatible alias for SSO_CONFIG_DICT. Existing installations can continue to use this name with no changes. If both are set, SSO_CONFIG_DICT takes precedence.

REQUIRE_SSO_LOGIN (optional)

  • Description: When enabled, Mathesar disables password-based login and only allows users to sign in via a configured SSO provider. Users will not be able to update passwords or email addresses. Administrators can still reset another user’s password and edit other users’ emails as a break-glass mechanism.
  • Format: true or false
  • Default value: false
  • Additional information:
    • This setting only takes effect when at least one SSO provider is configured. If REQUIRE_SSO_LOGIN=true but no provider is configured in sso.yml/SSO_CONFIG_DICT, Mathesar logs a warning and continues to allow password login (so administrators can never accidentally lock everyone out).

File backend configuration

OPTIONAL

Only needed if using file columns, in installations where the local filesystem is inaccessible.

FILE_STORAGE_DICT (optional)

  • Description: The configuration to connect Mathesar to an S3-compatible or Azure Blob Storage file storage backend.

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

    S3-compatible

     FILE_STORAGE_DICT="{\"default\":{\"protocol\":\"s3\",\"nickname\":\"Example\",\"prefix\":\"mathesar-storage\",\"kwargs\":{\"client_kwargs\":{\"endpoint_url\":\"https:\/\/storage-example.mathesar.org\",\"region_name\":\"auto\",\"aws_access_key_id\":\"XXX\",\"aws_secret_access_key\":\"XXX\"}}}}"

    Azure Blob Storage (managed identity)

     FILE_STORAGE_DICT="{\"default\":{\"protocol\":\"az\",\"nickname\":\"Example\",\"prefix\":\"mathesar-file-attachments\",\"kwargs\":{\"account_name\":\"my-storage-account\"}}}"

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

Datafiles storage configuration

OPTIONAL

Only needed if you want to store uploaded datafiles (used for CSV/TSV imports) in Azure Blob Storage instead of on the local filesystem.

DATA_FILES_STORAGE_BACKEND (optional)

  • Description: Selects the backend used to store uploaded datafiles. Set to azure to store them in Azure Blob Storage; otherwise they are stored on the local filesystem. Static files are always served by whitenoise regardless of this setting.
  • Format: One of local or azure
  • Default value: local

DATA_FILES_AZURE_ACCOUNT_NAME (optional)

  • Description: The Azure Storage account name used to store datafiles. Required when DATA_FILES_STORAGE_BACKEND is azure. Authentication uses DefaultAzureCredential, which resolves credentials from the environment (managed identity, workload identity, az login, etc.,).
  • Format: An Azure Storage account name

DATA_FILES_AZURE_CONTAINER (optional)

  • Description: The Azure Blob Storage container in which datafiles are stored. Required when DATA_FILES_STORAGE_BACKEND is azure.
  • Format: An Azure Blob Storage container name
  • Default value: mathesar-datafiles

Public entry and login page configuration

OPTIONAL

Only needed if you want to customize the public-facing login experience or redirect anonymous visitors from Mathesar’s home page.

MATHESAR_LANDING_PAGE_URL (optional)

  • Description: URL to redirect anonymous visitors who open Mathesar’s home page (/). If unset, anonymous visitors are sent to the login page.
  • Format: A URL
  • Default value: (none — anonymous visitors are sent to the login page)

MATHESAR_INSTANCE_NAME (optional)

  • Description: Name for this Mathesar instance. Currently used as accessible text for the logo on login/auth pages.
  • Format: Plain text
  • Default value: Mathesar

MATHESAR_AUTH_LOGO_URL (optional)

  • Description: URL for a custom logo shown on login/auth pages. If unset, Mathesar’s default auth logo is shown.
  • Format: An http:// or https:// URL, a root-relative Mathesar path such as /static/..., or a small data:image/...;base64,... URL.
  • Default value: (none — Mathesar’s default logo is shown)

MATHESAR_LOGIN_PAGE_TEXT_DICT (optional)

  • Description: Localized plain text copy shown on the login page. If unset, Mathesar uses the translated default heading (Log in to Mathesar) and no orientation copy.
  • Format: A stringified JSON representation of the config in a login_page.yml file. HTML and Markdown are not rendered.
  • Default value: {} (no custom login page copy)

  • Example:

    MATHESAR_LOGIN_PAGE_TEXT_DICT="{\"heading\":\"Welcome to your Mathesar workspace\",\"body\":\"Log in to continue working with your data.\",\"translations\":{\"es\":{\"heading\":\"Bienvenido a tu espacio de trabajo de Mathesar\",\"body\":\"Inicia sesión para seguir trabajando con tus datos.\"}}}"

  • Additional information: For Docker Compose, direct installations, and Kubernetes deployments that can mount files, prefer a login_page.yml file at Mathesar’s installation root. The file uses the same shape:

    heading: Welcome to your Mathesar workspace
body: Log in to continue working with your data.
translations:
  es:
    heading: Bienvenido a tu espacio de trabajo de Mathesar
    body: Inicia sesión para seguir trabajando con tus datos.

    MATHESAR_LOGIN_PAGE_TEXT_DICT takes precedence over login_page.yml. If custom copy is provided without translations, that custom copy is shown for all selected languages.

MATHESAR_LOGIN_PAGE_BACKGROUND (optional)

  • Description: CSS background value for the login page. This is intended for trusted administrators and can be a solid color, image URL, or layered gradient.
  • Format: CSS background value
  • Default value: (none — Mathesar’s default login page background is shown)
  • Additional information: If you set this in a dotenv-style file and the value contains # characters, wrap the value in quotes so the colors are not parsed as comments.

MATHESAR_TERMS_OF_SERVICE_URL (optional)

  • Description: URL for a “Terms of Service” link used in the login page legal notice.
  • Format: A URL
  • Default value: (none — no link is shown)

MATHESAR_PRIVACY_POLICY_URL (optional)

  • Description: URL for a “Privacy Policy” link used in the login page legal notice.
  • Format: A URL
  • Default value: (none — no link is shown)