Secrets (Environment Variables)

Introduction

Secrets, also known as env variables, control system level settings of Diffgram.

For production, the env should be loaded through a secrets manager, such as built into your CI/CD process. There are multiple ways to load secrets. Be sure whatever process you choose enables secret rotation in line with your security posture.

Concepts

System settings for Diffgram are loaded from Environment Variables. (In settings/settings.py.)

How to Check Secrets

See Super Admin Info

Secrets Issues

Conflicting or invalid secrets can be the source of hard to debug issues. While the system attempts some self checks, it's best if you configure secrets very carefully. For example if you have two files loading or setting storage secrets at the same time you could run into unexpected issues such as a file appearing to upload and then not having a valid signature for the signed URL.

How to Set Secrets for Production

Set the Secrets (Environment Variables) through an Secrets Service like Github Envs, Key Vault or another external loading method.

It is the SysAdmin responsibility to set the correct values of the settings depending on the use case of Diffgram. Note that Diffgram sets defaults to many settings.

See Production Installation

How to Set Secrets for Dev

Follow loading as per company guidelines or for purely local dev (no "real" secrets) you can use a .env file.

The Diffgram Dev Installer generates an example .env file which must be verified for your specific case.

Local Baremetal Dev Loading

Settings.py will attempt to load an env file .env by default, using python-dotenv. You can customize this naming scheme in the settings.py file if needed.

Please note that settings.py only loads existing env variables, and that setting a .env file by itself in python is not enough. Therefore python-dotenv will attempt to load it for you. Check load_local_dev_env() if it is not working as expected. By default, this will only load if DOCKER_CONTEXT=False. We assume in a production env DOCKER_CONTEXT=True.

Frontend and Backend Env

The backend envs sets secrets in a different context then frontend.

External Loading Examples

Secrets are always loaded from Environment Variables. However, those can be set by another program, or loaded from another source, here are some of the ways you can load settings on Diffgram.

values.yaml for K8s deployments

We also offer a Helm Chart for Diffgram. You can configure the env variables by editing the values.yaml of the helm chart.

.env file for docker compose

In our docker compose file, we load all env variables from the .env file located at the project root. This file contains default values for a standard installation, feel free to inspect this file to see all the configurations available.

Secrets Table

All secrets in Diffgram are set via environment variables.

General

Value	Type	Notes	Example
FERNET_KEY		Must be generated with Fernet Library
DIFFGRAM_STATIC_STORAGE_PROVIDER	string
DIFFGRAM_MINIO_ENDPOINT_URL	string
URL_BASE	string	See Domain Configuration
WALRUS_SERVICE_URL_BASE	string	See Domain Configuration
DATABASE_URL	string

Mail

See Setup Email SMTP Provider

Defaults

We have certain default values for secrets in settings.py but they should be for local usage only and are discouraged for using in production.

Please make sure to set the secrets on environment variables and to keep strong security policies for the management and access of your production secrets, database password, access keys, etc.

General Concepts

Some important assumptions about the settings variable names:

• We assume that all settings variables are CAPITALIZED. This is so it's easier to get them from the OS's environment variables.
• In DIFFGRAM_SYSTEM_MODE=='production' secrets are not logged, or logged in safe way, eg bool(secret). In development secrets may be logged. Secrets are never sent to Diffgram Hub.