Customize your environment file

Your .env (environment) file contains variables you can change to customize your pod. You can change these variables at any time to alter how your pod runs.

You need to restart your Funkwhale services after changing your .env file.

sudo systemctl restart funkwhale.target

docker compose restart

Variables

Important

Some environment variables accept a URL as a value. To encode URLs and avoid problems with special characters, use urllib.parse on your URL value.

python3 -c 'import urllib.parse; print(urllib.parse.quote_plus("p@ssword"))

See also

The django-environ documentation.

Pod configuration

FUNKWHALE_HOSTNAME = mypod.audio

Hostname of your Funkwhale pod, e.g. mypod.audio.

FUNKWHALE_PROTOCOL =  https

Protocol end users will use to access your pod, either http or https.

Database and redis configuration

DATABASE_URL = postgresql://<user>:<password>@<host>:<port>/<database>

The URL used to connect to the PostgreSQL database. Defaults to an auto generated url build using the DATABASE_HOST, DATABASE_PORT, DATABASE_USER, DATABASE_PASSWORD and DATABASE_NAME variables.

Examples: - postgresql://funkwhale@:5432/funkwhale - postgresql://<user>:<password>@<host>:<port>/<database> - postgresql://funkwhale:passw0rd@localhost:5432/funkwhale_database

DB_CONN_MAX_AGE = 300

The maximum time in seconds before database connections close.

CACHE_URL = redis://<host>:<port>/<database>

The URL of your redis server. For example:

  • redis://<host>:<port>/<database>

  • redis://127.0.0.1:6379/0

  • redis://:password@localhost:6379/0

If you’re using password auth (the extra slash is important) - redis:///run/redis/redis.sock?db=0 over unix sockets

Note

If you want to use Redis over unix sockets, you also need to update CELERY_BROKER_URL, because the scheme differs from the one used by CACHE_URL.

CELERY_BROKER_URL = redis://127.0.0.1:6379/0

The celery task broker URL. Defaults to CACHE_URL. You don’t need to tweak this unless you want to use a different server or use Redis sockets to connect.

Example:

  • unix://127.0.0.1:6379/0

  • redis+socket:///run/redis/redis.sock?virtual_host=0

Accounts and registration

ACCOUNT_EMAIL_VERIFICATION_ENFORCE = true

Set whether users need to verify their email address before using your pod. Enabling this setting is useful for reducing spam and bot accounts. To use this setting you need to configure a mail server to send verification emails. See EMAIL_CONFIG.

Note

Superusers created through the command line never need to verify their email address.

USERS_INVITATION_EXPIRATION_DAYS = 7

The number of days before a user invite expires.

DISABLE_PASSWORD_VALIDATORS = true

Whether to disable password validation rules during registration. Validators include password length, common words, similarity with username.

ACCOUNT_USERNAME_BLACKLIST = test,funkwhale

List of usernames that can’t be used for registration. Given as a list of strings.

LDAP_ENABLED = False

Whether to enable LDAP authentication.

See Configure LDAP for more information.

Media storage and serving configuration

MEDIA_URL = https://mypod.audio/media/

The URL from which your pod serves media files. Change this if you’re hosting media files on a separate domain, or if you host Funkwhale on a non-standard port.

MEDIA_ROOT = /srv/funkwhale/data/media

The path where you store media files (such as album covers or audio tracks) on your system. Make sure this directory actually exists.

PROXY_MEDIA = true

Whether to proxy audio files through your reverse proxy. We recommend you leave this enabled to enforce access control.

If you’re using S3 storage with AWS_QUERYSTRING_AUTH enabled, it’s safe to disable this setting.

EXTERNAL_MEDIA_PROXY_ENABLED = false

Whether to proxy attachment files hosted on third party pods and and servers. We recommend you leave this set to true. This reduces the risk of leaking user browsing information and reduces the bandwidth used on remote pods.

ATTACHMENTS_UNATTACHED_PRUNE_DELAY = true

The delay in seconds before Funkwhale prunes uploaded but detached attachments from the system.

REVERSE_PROXY_TYPE = nginx

Set your reverse proxy type. This changes the headers the API uses to serve audio files. Allowed values:

  • nginx

  • apache2

PROTECT_FILES_PATH = /_protected

The path used to process internal redirection to the reverse proxy.

Important

Don’t insert a slash at the end of this path.

NGINX_MAX_BODY_SIZE = 100M

Controls the maximum size of file that users can upload.

Note

You can control how much total storage a user can access with the Upload Quota setting.

S3 storage configuration

AWS_QUERYSTRING_AUTH = False

Whether to include signatures in S3 URLs. Signatures are used to enforce access control.

Defaults to the opposite of PROXY_MEDIA.

AWS_QUERYSTRING_EXPIRE = 3600

The time in seconds before AWS signatures expire. Only takes effect you enable AWS_QUERYSTRING_AUTH

AWS_ACCESS_KEY_ID = 'my_access_key'

Access-key ID for your S3 storage.

AWS_SECRET_ACCESS_KEY = 'my_secret_key'

Secret access key for your S3 storage.

AWS_STORAGE_BUCKET_NAME = 'my_bucket'

Your S3 bucket name.

AWS_S3_CUSTOM_DOMAIN = None

Custom domain for serving your S3 files.

Useful if your provider offers a CDN-like service for your bucket.

Important

The URL must not contain a scheme (AWS_S3_URL_PROTOCOL is automatically prepended) nor a trailing slash.

AWS_S3_ENDPOINT_URL = https://minio.mydomain.com

If you use a S3-compatible storage such as minio, set the following variable to the full URL to the storage server.

Examples:

  • https://minio.mydomain.com

  • https://s3.wasabisys.com

AWS_S3_REGION_NAME = eu-west-2

If you’re using Amazon S3 to serve media without a proxy, you need to specify your region name to access files.

Example:

  • eu-west-2

AWS_LOCATION = funkwhale_music

A directory in your S3 bucket where you store files. Use this if you plan to share the bucket between services.

In-place import configuration

MUSIC_DIRECTORY_PATH = /srv/funkwhale/data/music

The path on your server where Funkwhale places files from in-place imports. This path needs to be readable by the webserver and api and worker processes.

Important

Don’t insert a slash at the end of this path.

On Docker installations, we recommend you use the default /music path. On Debian installations you can use any absolute path. Defaults to /srv/funkwhale/data/music.

Note

You need to add this path to your reverse proxy configuration. Add the directory to your /_protected/music server block.

MUSIC_DIRECTORY_SERVE_PATH = /srv/funkwhale/data/music

On Docker setups the value of MUSIC_DIRECTORY_PATH may be different from the actual path on your server. You can specify this path in your docker-compose.yml file:

volumes:
    - /srv/funkwhale/data/music:/music:ro

In this case, you need to set MUSIC_DIRECTORY_SERVE_PATH to /srv/funkwhale/data/music. The webserver needs to be able to read this directory.

Important

Don’t insert a slash at the end of this path.

API configuration

THROTTLING_ENABLED = True

Whether to enable throttling (also known as rate-limiting). We recommend you leave this enabled to improve the quality of the service, especially on public pods .

THROTTLING_RATES = signup=5/d,password-reset=2/d,anonymous-reports=5/d

Throttling rates for specific endpoints and app features. Tweak this if you’re hitting rate limit issues or if you want to reduce the consumption of specific endpoints. Takes the format <endpoint name>=<number>/<interval>.

Example:

  • signup=5/d,password-reset=2/d,anonymous-reports=5/d

See Rate limit API endpoints for a list of available endpoints and their default limits.

ADMIN_URL = '^api/admin/'

Path to the Django admin dashboard.

Examples:

  • ^api/admin/

  • ^api/mycustompath/

EXTERNAL_REQUESTS_VERIFY_SSL = True

Whether to enforce TLS certificate verification when performing outgoing HTTP requests.

We recommend you leave this setting enabled.

EXTERNAL_REQUESTS_TIMEOUT = 10

Default timeout for external requests.

Federation configuration

FEDERATION_OBJECT_FETCH_DELAY = 4320

The delay in minutes before a remote object is automatically refetched when accessed in the UI.

FEDERATION_DUPLICATE_FETCH_DELAY = 3000

The delay in seconds between two manual fetches of the same remote object.

Metadata configuration

TAGS_MAX_BY_OBJ = 30

Maximum number of tags that can be associated with an object. Extra tags are ignored.

MUSICBRAINZ_HOSTNAME = 'musicbrainz.org'

The hostname of your MusicBrainz instance. Change this setting if you run your own server or use a mirror. You can include a port number in the hostname.

Examples:

  • mymusicbrainz.mirror

  • localhost:5000

MUSICBRAINZ_CACHE_DURATION = 300

Length of time in seconds to cache MusicBrainz results.

Channels and podcast configuration

PODCASTS_RSS_FEED_REFRESH_DELAY = 86400

The delay in seconds between two fetch of RSS feeds.

A lower rate means new episodes are fetched sooner, but requires more resources.

PODCASTS_RSS_FEED_MAX_ITEMS = 250

Maximum number of RSS items to load in each podcast feed.

PODCASTS_THIRD_PARTY_VISIBILITY = 'me'

By default, only people who subscribe to a podcast RSS have access to its episodes. Change to instance or everyone to change the default visibility.

Note

Changing this value only affect new podcasts.

Subsonic configuration

SUBSONIC_DEFAULT_TRANSCODING_FORMAT = 'mp3'

The default format files are transcoded into when using the Subsonic API.

Email configuration

EMAIL_CONFIG = consolemail://

SMTP configuration for sending emails. Possible values:

  • EMAIL_CONFIG=consolemail://: output emails to console (the default)

  • EMAIL_CONFIG=dummymail://: disable email sending completely

On a production instance, you’ll usually want to use an external SMTP server:

  • EMAIL_CONFIG=smtp://user:password@youremail.host:25

  • EMAIL_CONFIG=smtp+ssl://user:password@youremail.host:465

  • EMAIL_CONFIG=smtp+tls://user:password@youremail.host:587

DEFAULT_FROM_EMAIL = Funkwhale <noreply@yourdomain>

The name and email address used to send system emails. Defaults to Funkwhale <noreply@yourdomain>.

Available formats:

  • Name <email address>

  • <Email address>

EMAIL_SUBJECT_PREFIX = '[Funkwhale] '

Subject prefix for system emails.

Plugin configuration

FUNKWHALE_PLUGINS_PATH = '/srv/funkwhale/plugins/'

Path to a directory containing Funkwhale plugins. These are imported at runtime.

FUNKWHALE_PLUGINS = ['funkwhale_api.contrib.scrobbler', 'funkwhale_api.contrib.listenbrainz', 'funkwhale_api.contrib.maloja']

List of Funkwhale plugins to load.

Other settings

INSTANCE_SUPPORT_MESSAGE_DELAY = 15

The number of days before your pod shows the “support your pod” message. The timer starts after the user signs up.

FUNKWHALE_SUPPORT_MESSAGE_DELAY = 15

The number of days before your pod shows the “support Funkwhale” message. The timer starts after the user signs up.

MIN_DELAY_BETWEEN_DOWNLOADS_COUNT = 21600

The required number of seconds between downloads of a track by the same IP or user to be counted separately in listen statistics.

MARKDOWN_EXTENSIONS = ['nl2br', 'extra']

A list of markdown extensions to enable.

See https://python-markdown.github.io/extensions/.

LINKIFIER_SUPPORTED_TLDS = ['audio']

Additional TLDs to support with our markdown linkifier.

LOGLEVEL = info

Default logging level for the Funkwhale processes.

Note

The DEBUG variable overrides the LOGLEVEL if it is set to TRUE.

The LOGLEVEL value only applies if DEBUG is false or not present.

Available levels:

  • debug

  • info

  • warning

  • error

  • critical