Instance configuration

General configuration is achieved using two type of settings.

Environment variables

Those are located in your .env file, which you should have created during installation.

Options from this file are heavily commented, and usually target lower level and technical aspects of your instance, such as database credentials.


You should restart all funwhale processes when you change the values on environment variables.

Instance settings

Those settings are stored in database and do not require a restart of your instance after modification. They typically relate to higher level configuration, such your instance description, signup policy and so on.

You can edit those settings directly from the web application, assuming you have the required permissions. The URL is /manage/settings, and you will also find a link to this page in the sidebar.

If you plan to use acoustid and external imports (e.g. with the youtube backends), you should edit the corresponding settings in this interface.


If you have any issue with the web application, a management interface is also available for those settings from Django’s administration interface. It’s less user friendly, though, and we recommend you use the web app interface whenever possible.

The URL should be /api/admin/dynamic_preferences/globalpreferencemodel/ (prepend your domain in front of it, of course).

Configuration reference


Determine how emails are sent.

Default: consolemail://

Possible values:

  • consolemail://: Output sent emails to stdout
  • dummymail://: Completely discard sent emails
  • smtp:// Send emails via SMTP via on port 25, without encryption, authenticating as user “user” with password “password”
  • smtp+ssl:// Send emails via SMTP via on port 465, using SSL encryption, authenticating as user “user” with password “password”
  • smtp+tls:// Send emails via SMTP via on port 587, using TLS encryption, authenticating as user “user” with password “password”


The email address to use to send email.

Default: Funkwhale <noreply@yourdomain>


Both the forms Funkwhale <noreply@yourdomain> and noreply@yourdomain work.


Default: None

The path on your server where Funwkhale can import files using in-place import. It must be readable by the webserver and Funkwhale api and worker processes.

On docker installations, we recommend you use the default of /music for this value. For non-docker installation, you can use any absolute path. /srv/funkwhale/data/music is a safe choice if you don’t know what to use.


This path should not include any trailing slash


You need to adapt your reverse-proxy configuration to serve the directory pointed by MUSIC_DIRECTORY_PATH on /_protected/music URL.



When using Docker, the value of MUSIC_DIRECTORY_PATH in your containers may differ from the real path on your host. Assuming you have the following directive in your docker-compose.yml file:

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

Then, the value of MUSIC_DIRECTORY_SERVE_PATH should be /srv/funkwhale/data/music. This must be readable by the webserver.

On non-docker setup, you don’t need to configure this setting.


This path should not include any trailing slash


Default: nginx

The type of reverse-proxy behind which Funkwhale is served. Either apache2 or nginx. This is only used if you are using in-place import.

User permissions

Funkwhale’s permission model works as follows:

  • Anonymous users cannot do anything unless configured specifically
  • Logged-in users can use the application, but cannot do things that affect the whole instance
  • Superusers can do anything

To make things more granular and allow some delegation of responsability, superusers can grant specific permissions to specific users. Available permissions are:

  • Manage instance-level settings: users with this permission can edit instance settings as described in Instance settings
  • Manage library: users with this permission can import new music in the instance
  • Manage library federation: users with this permission can ask to federate with other instances, and accept/deny federation requests from other intances

There is no dedicated interface to manage users permissions, but superusers can login on the Django’s admin at /api/admin/ and grant permissions to users at /api/admin/users/user/.