Warning

This documentation only applies for the development version of Funkwhale! Visit the docs for the latest release.

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.

    venv/bin/funkwhale-manage fix_federation_ids https://old-url https://new-url --no-dry-run --no-input
    
    sudo 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.

    sudo systemctl restart nginx
    
    sudo systemctl restart apache2