Configuration

Magritte is designed to run in a wide range of deployment scenarios, so most of its behavior is configurable.

Specifying Configuration

Magritte reads its configuration from three places, from lowest to highest priority:

1. A .env file in your current working directory
2. The environment you start it from – I.e. your shell or a docker compose file
3. An env file in Magritte’s data directory

When a key is set in more than one place, the higher-priority source wins. Keys in the data directory’s env file always take effect, even if the same key is set in the environment.

Configuration files use the format supported by python-dotenv, with one KEY=value pair per line:

ENV=prod

Supported Options

Storage

Docker

By default, Magritte stores its data at /data, looks for music files in /music, and uses an SQLite3 database.

Key	Description	Type	Default
DATA_HOME	Directory where the instance stores data	str	/data
MUSIC_HOME	Directory where libraries find music files	str	/music
DB	URL used to connect to the database	str	sqlite+aiosqlite:///$HOME/.magritte/db.sqlite3

Other

By default, Magritte stores its data in a hidden folder in your home directory, looks for music files in your Music folder, and uses a SQLite3 database. If you are running Magritte somewhere other than your own computer, you can change any of these.

Key	Description	Type	Default
DATA_HOME	Directory where the instance stores data	str	$HOME/.magritte
MUSIC_HOME	Directory where libraries find music files	str	$HOME/Music
DB	URL used to connect to the database	str	sqlite+aiosqlite:///$HOME/.magritte/db.sqlite3

Uploads

Magritte can let users upload new music files. Uploads are disabled by default.

Key	Description	Type	Default
ENABLE_UPLOADS	Whether users can upload music files	bool	false
UPLOAD_MAX_FILE_SIZE	Maximum size of an uploaded file, in bytes	int	1073741824 (1 GiB)

Account Emails

Magritte can associate email addresses with user accounts when configured to be able to send emails. This enables features such as password recovery and notifications. Magritte supports multiple methods for sending emails:

SMTP

Magritte can send emails through an SMTP server.

Key	Description	Type	Default
EMAIL_SMTP	URL of an SMTP server to send emails through	str	Not set

The credentials and transport are specified in a URL:

No encryption

smtp://user:password@server

TLS

smtp+tls://user:password@server

Start TLS

smtp+starttls://user:password@server

Mailtrap

Magritte can send emails through Mailtrap. Generate an API key and add it to your configuration.

Key	Description	Type	Default
EMAIL_MAILTRAP_API_KEY	Mailtrap API key used to send emails	str	Not set

Important: You must set EMAIL_SENDER_ADDRESS to an email address from the domain you’ve verified with Mailtrap, otherwise sending will silently fail.

---

Keys common to all methods of sending emails:

Key	Description	Type	Default
WEB_URL	Public URL of this instance, used for links in emails	str	http://localhost:8090
EMAIL_SENDER_ADDRESS	Address that emails from this instance are sent from	str	noreply@localhost:8090

Secrets

Magritte uses random secret values to sign the tokens that control access to user data, and a random salt when storing passwords.

Desktop

On a desktop-class machine, such as a development environment, Magritte generates these secrets automatically and stores them in your keyring (Keychain, KWallet, etc.).

Docker

The first time containerized Magritte starts, it will automatically create these secrets and write them to $DATA_HOME/env if it does not already exist.

Other

If you are running Magritte outside of a container and do not have the desktop extras installed or otherwise do not have a keyring available, you can have magritte generate secrets for you:

$ magritte generate-secrets

Add the output to your environment or to one of the configuration files mentioned above.

---

The keys for manually specifying secrets are:

Key	Description	Type	Default
TOKEN_ALGORITHM	Algorithm used to sign tokens	str	HS256
SESSION_TOKEN_SECRET	Random secret used to sign session tokens	str	Not set
FEATURE_TOKEN_SECRET	Random secret used to sign feature-specific tokens	str	Not set
SALT	Random salt added to passwords before storage	str	Not set

Other

If you are deploying a Magritte instance, make sure ENV is set correctly.

Key	Description	Type	Default
ENV	Environment the server is running in	dev, ci, prod	prod