Change your instance URL

Danger

We recommend you don’t change your instance URL. Changing it will cause instability and problems with federation. If you change your URL, the Funkwhale project can’t offer support for problems that arise.

Your instance URL is your pod’s unique identifier in the fediverse. If you want to change it, you need to update a lot of information

• The instance URL in your .env file.

• The instance URL in your webserver config.

• Any references to the old URL in your database.

To clean the database, the funkwhale-manage command line interface contains a fix_federation_ids command.

Warning

Running fix_federation_ids with the --no-dry-run flag is irreversible. Make sure you back up your data.

Update your instance URL

1. Change the FUNKWHALE_HOSTNAME and DJANGO_ALLOWED_HOSTS value in your .env file.

2. Change the server_name values in your /etc/nginx/sites-enabled/funkwhale.conf file.

3. Run the fix_federation_ids command to clean up your database.

   Debian

   venv/bin/funkwhale-manage fix_federation_ids https://old-url https://new-url --no-dry-run --no-input
   

   Docker

   docker compose run --rm api funkwhale-manage fix_federation_ids https://old-url https://new-url --no-dry-run --no-input
   

   Example output:

   Will replace 108 found occurrences of 'https://old-url' by 'https://new-url':
   
   - 20 music.Artist
   - 13 music.Album
   - 39 music.Track
   - 31 music.Upload
   - 1 music.Library
   - 4 federation.Actor
   - 0 federation.Activity
   - 0 federation.Follow
   - 0 federation.LibraryFollow
   
   Replacing on 20 music.Artist…
   Replacing on 13 music.Album…
   Replacing on 39 music.Track…
   Replacing on 31 music.Upload…
   Replacing on 1 music.Library…
   Replacing on 4 federation.Actor…
   Replacing on 0 federation.Activity…
   Replacing on 0 federation.Follow…
   Replacing on 0 federation.LibraryFollow…
   

4. Restart your webserver to pick up the changes.

   Nginx

   sudo systemctl restart nginx
   

   Apache

   sudo systemctl restart apache2