Environment Variables

Authored by briiian and Claude · Last updated November 3, 2026Written with AI by reading the source code, and edited by hand

self-hosted

---

These environment variables can be set in your docker-compose.yaml file. All variables are optional.

Name	Type	Default	Description
MUSIC_DIR	string	undefined	Absolute path to your music.
PHOTOS_DIR	string	undefined	Absolute path to your photos.
MOVIES_DIR	string	undefined	Absolute path to your movies.
TV_DIR	string	undefined	Absolute path to your TV shows.
CARDINAL_MEDIA_SERVER_PORT	number	24900	The port the Media Server listens on. The container image sets it to 24900, which is the port the Quick Start publishes; outside a container it falls back to 3080. Change it and you must publish the same port in your compose file, and point anything in front of the server — such as a reverse proxy — at the new one.
HTTP_LOG_LEVEL	number	0	Set the log level¹ for HTTP requests.
EVENTS_LOG_LEVEL	number	0	Set the log level¹ for the internal event system.
INDEXING_LOG_LEVEL	number	10	Set the log level¹ for the indexing system.
JOBS_LOG_LEVEL	number	10	Set the log level¹ for the jobs system.
TRANSCODER_LOG_LEVEL	number	0	Set the log level¹ for the transcoding system.
DATABASE_LOG_LEVEL	number	0	Set the log level¹ for database queries.
MAX_CONCURRENT_JOBS	number	3	Max number of jobs that are allowed to run at the same time.
SQLITE_PATH	string	undefined	Absolute path for where the server should store the SQLite database. Set to :memory: to use an in-memory database. When omitted, the server will automatically choose a location based on the operating system. If you change this after the server has already created a database, then you will need to copy the database to the new location manually.
SQLITE_WAL	boolean	false	Enable Write-Ahead Logging (WAL) for SQLite. This is a significant performance optimization that allows for concurrent read/writes, but it cannot be enabled if your database is being used over a network connection (NFS, SMB, etc). Changing this requires a server restart.
CARDINAL_POSTGRES	boolean	false	Use PostgreSQL instead of the default SQLite.
POSTGRES_HOST	string	undefined	PostgreSQL host name. When omitted, the server connects to the database service from the Quick Start examples (cardinal-media-server-<channel>-postgres-db), or 127.0.0.1 when running outside a container.
POSTGRES_PORT	number	5432	PostgreSQL port number.
POSTGRES_USER	string	cardinal	The PostgreSQL user.
POSTGRES_PASSWORD	string	cardinal	The PostgreSQL user password.
POSTGRES_DATABASE	string	—	PostgreSQL database name. Uses your Postgres user name if omitted.
POSTGRES_SSL	boolean	false	Enable SSL for the PostgreSQL connection.
SECURE_COOKIES	boolean	false	Allow the Media Server to issue cookies with stricter security settings. See Media Server → Accounts for more information on how sessions work.
SIGNING_SECRET	string	undefined	Secret used to sign authentication tokens. Changing this will revoke all sessions. One is generated automatically and stored in the app directory if none is provided. If the app directory cannot be read or written and this is not set, the server refuses to start. A blank value is refused; use at least 32 random characters.
RESET_LOCAL_USER_PW	string	undefined	Set this to the username of a local user to reset their password on the next startup. Their new password will be printed in the console.
INDEXING_SCAN_TIMEOUT	number	120	Number of seconds the scanner will wait for the file system to respond.
INDEXING_SCAN_VERIFY_PASSES	number	4	Maximum number of verification passes the music scanner will make over the file system to confirm that the initial scan did not miss any files. Verification ends early once a pass finds nothing new. Mostly useful for unreliable file systems, like network shares.
HEIF_CONVERSION_TIMEOUT	number	60	Number of seconds before we assume that the conversion failed.
FFMPEG_PATH	string	undefined	Absolute path to an ffmpeg binary, used for transcoding audio, generating waveforms, and video features. When omitted, the bundled build is used. Set this to use your own build of FFmpeg.
FFPROBE_PATH	string	undefined	Absolute path to an ffprobe binary, used to read the streams, codecs, HDR format and chapters of your video files. When omitted, the bundled build is used. When no ffprobe can be found, video files are still indexed, with less detail.
TRANSCODE_MAX_FULL_SESSIONS	number	2	How many videos Cinema may convert at once when a player can't decode the picture, or when a remote player asks for a lower bitrate. Each one keeps several CPU cores busy, so raise this only on a machine with cores to spare. A player asking for one more is told the server is busy. Set 0 to never convert video.
TRANSCODE_MAX_LIGHT_SESSIONS	number	6	How many videos Cinema may prepare at once by converting only their audio, or by repackaging them without converting anything. These are light on the CPU. Set 0 to turn them off.
TRANSCODE_DISK_BUDGET_GB	number	20	Disk space, in GB, that converted video may use at once. Each viewer's stream keeps about a minute behind and a minute ahead of where they are watching, in the server's data directory under transcode; it is deleted when they stop, after two idle minutes, and when the server starts.
CONNECT_LAN_IPS	string	undefined	Optional. Addresses this machine has on your own network, which Remote Access advertises as local connection routes for this server. Cardinal apps that look the server up through Cardinal's cloud try local routes first, then fall back to the public ones — a direct connection through your router, or the relay. Separate several addresses with commas. A server inside a Docker bridge network (the Quick Start default) cannot discover its machine's addresses, so without this it advertises no local routes. This setting has no effect on the server's connect.cardinalapps.host address, which always points at your public address, and none on reaching the server by IP on your own network.

¹ Available log levels are:

• 20 - Debug
• 10 - Info
• 0 - Silent

Higher numbers include logs from lower numbers. Setting 0 does not disable error logging.

FFmpeg

The Docker image ships with FFmpeg, as the ffmpeg and ffprobe programs next to the Media Server. They are the static Linux GPL build published by BtbN/FFmpeg-Builds, used unmodified, and are not part of Cardinal Media Server.

FFmpeg is licensed under the GNU General Public License, version 3. The license text and the exact build and source it came from are in /home/node/bin/licenses/ffmpeg/ inside the container. The build enables no nonfree components, so it does not include the FDK AAC encoder.

The standalone binary from the releases page does not include FFmpeg. Install ffmpeg and ffprobe with your system's package manager, or point FFMPEG_PATH and FFPROBE_PATH at a build of your choice.

Was this article helpful?