Skip to content
Snippets Groups Projects
Commit 17f1941b authored by Ciarán Ainsworth's avatar Ciarán Ainsworth
Browse files

Rewrite admin documentation

parent f0857ae5
No related branches found
No related tags found
No related merge requests found
Expand all Show whitespace changes
Inline Side-by-side
Showing
with 124 additions and 2423 deletions
CHANGELOG
+ 2
− 2
View file @ 17f1941b
...@@ -3587,8 +3587,8 @@ without developping our own alternative clients for each and every platform. ...@@ -3587,8 +3587,8 @@ without developping our own alternative clients for each and every platform.
Most advanced Subsonic clients support offline caching of music files, Most advanced Subsonic clients support offline caching of music files,
playlist management and search, which makes them well-suited for nomadic use. playlist management and search, which makes them well-suited for nomadic use.
Please head over :doc:`users/apps` for more informations about supported clients Please see `our list of supported apps <https://funkwhale.audio/en_US/apps>`_
and user instructions. for more informations about supported clients and user instructions.
At the instance-level, the Subsonic API is enabled by default, but require At the instance-level, the Subsonic API is enabled by default, but require
and additional endpoint to be added in you reverse-proxy configuration. and additional endpoint to be added in you reverse-proxy configuration.
......
api/config/settings/common.py
+ 121
− 121
View file @ 17f1941b
This diff is collapsed.
changes/changelog.d/admin_docs.enhancement 0 → 100644
+ 1
− 0
View file @ 17f1941b
All administrator documentation has been rewritten to improve clarity and update outdated information.
docs/admin/0.17.rst deleted 100644 → 0
+ 0
− 214
View file @ f0857ae5
About Funkwhale 0.17
====================
Funkwhale 0.17 is a special version, which contains a lot of breaking changes.
Before doing the upgrade, please read this document carefully.
Overview of the changes
^^^^^^^^^^^^^^^^^^^^^^^
.. note::
The what and why are described more thoroughly in this page: https://dev.funkwhale.audio/funkwhale/funkwhale/merge_requests/368
To sum it up, this release big completely changes the way audio content is managed in Funkwhale.
As you may guess, this has a huge impact on the whole project, because audio is at the
core of Funkwhale.
Here is a side by side comparison of earlier versions and this release
to help you understand the scale of the changes:
+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Before | After | Reason |
+========================================================================================+=================================================================================================+=========================================================================================================================================================================================================================================================+
| There is one big audio library, managed at the instance level | Each user can have their own libraries (either public, private or shared at the instance level) | Managing the library at instance was cumbersome and dangerous: sharing an instance library over federation would quickly pose copyright issues, as well as opening public instances. It also made it impossible to only share a subset of the music. |
+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Users needed a specific permissions from instance owners to upload audio content | Users can upload music to their own libraries without any specific permissions | This change makes it easier for new users to start using Funkwhale, and for creators to share their content on the network. |
+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Users with permissions can upload as much content as they want in the instance library | Users have a storage quota and cannot exceed that storage | This change gives visibiliy to instance owners about their resource usage. If you host 100 users with a 1Gb quota, you know that your Funkwhale instance will not store more than 100Gb of music files. |
+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| N/A | Users can upload private content or share content with only specific users | This is a new feature, and we think it will enable users to upload their own music libraries to their instance, without breaking the law or putting their admins in trouble, since their media will remain private. |
+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Youtube Import | This feature is removed | This feature posed copyright issues and impacted the credibility of the project, so we removed it. |
+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Music requests | This feature is removed | Since all users can now upload content without specific permissions, we think this feature is less-likely to be useful in its current state. |
+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
From a shared, instance-wide library to users libraries
-------------------------------------------------------
As you can see, there is a big switch: in earlier versions, each instance had one big library,
that was available to all its users. This model don't scale well (especially if you put
federation on top of that), because it's an all-or-nothing choice if you want to share it.
Starting from version 0.17, each user will be able to create personal libraries
and upload content in those, up to a configurable quota.
Those libraries can have one of the following visibility level:
- **Private**: only the owner of the library can access its content
- **Instance**: users from the same instance can access the library content
- **Public**: everyone (including other instances) can access the library content
Regardless of this visibility level, library owners can also share them manually
with other users, both from the same instance or from the federation.
We think this change will have a really positive impact:
- Admins should be more inclined to open their instance to strangers, because copyrighted media
can be upload and shared privately
- Creators should have a better experience when joining the network, because they can now
upload their own content and share it over the federation without any admin intervention
- The federation should grow faster, because user libraries can contain copyrighted content
and be shared, without putting the admins at risk
Accessing music
---------------
From an end-user perspective, you will be able to browse any artist or album or track
that is known by your instance, but you'll only be able to listen to content
that match one of those criteria:
- The content is available is one of your libraries
- The content is available in a public library
- The content is available in one library from your instance that has a visibility level set to "instance"
- The content is available in one of the libraries you follow
Following someone else's library is a four step process:
1. Get the library link from its owner
2. Use this link on your instance to follow the library
3. Wait until your follow request is approved by the library owner
4. If this library is unknown on your instance, it will be scanned to import its content, which may take a few minutes
Libraries owner can revoke follows at any time, which will effectively prevent
the ancient follower from accessing the library content.
A brand new federation
----------------------
This is more "under the hood" work, but the whole federation/ActivityPub logic
was rewritten for this release. This new implementation is more spec compliant
and should scale better.
The following activities are propagated over federation:
- Library follow creation, accept and reject
- Audio creation and deletion
- Library deletion
A better import UI
------------------
This version includes a completely new import UI which should make
file uploading less annoying. In particular, the UI updates in real-time
and has a better error reporting.
A better import engine
----------------------
Funkwhale is known for its quircks during music import. Missing covers,
split albums, bad management of tracks with multiple artists, missing
data for files imported over federation, bad performance, discrepancies between
the user-provided tags and what is actually stored in the database...
This should be greatly improved now, as the whole import logic was rewritten
from scratch.
Import is done completely offline and no longer calls the MusicBrainz API,
except to retrieve covers if those are not embedded in the imported files.
MusicBrainz references are still stored in the database, but we rely solely
on the tags from the audio file now.
This has two positive consequences:
- Improved performance for both small and big imports (possibly by a factor of 10)
- More reliable import result: if your file is tagged in a specific way, we will only
use tags for the import.
Imports from federation, command-line and UI/API all use the same code,
which should greatly reduce the bugs/discrepencies.
Finally, the import engine now understands the difference between a track artist
and an album artist, which should put an end to the album splitting issues
for tracks that had a different artist than the album artist.
What will break
---------------
If you've read until here, you can probably understand that all of these changes
comes at a cost: version 0.17 contains breaking changes, removed features and other
changes.
The following features were removed:
- YouTube imports: for copyright reasons, keeping this in the core was not possible
- Music requests: those are now less useful since anyone can upload content
Also, the current federation will break, as it's absolutely not compatible
with what we've built in version 0.17, and maintaining compatibility was simply not possible.
Apart from that, other features should work the same way as they did before.
Migration path
--------------
.. warning::
This migration is huge. Do a backup. Please. The database, and the music files.
Please.
.. warning:: I'm not kidding.
Migration will be similar to previous ones, with an additional script to run that will
take care of updating existing rows in the database. Especially, this script
will be responsible to create a library for each registered user, and to
bind content imported by each one to this library.
Libraries created this way will have a different visibility level depending of your instance configuration:
- If your instance requires authentication to access the API / listen to music, libraries will
be marked with "instance" visibility. As a result, all users from the instance will still
be able to listen to all the music of the instance after the migration
- If your instance does not require authentication to access the API / listen to music,
libraries will be completely public, allowing anyone to access the content (including federation)
This script will also contain other database-related operations, but the impact will remain
invisible.
Upgrade instructions
--------------------
Follow instructions from https://docs.funkwhale.audio/upgrading/index.html,
then run the migrations script.
On docker-setups::
# if you missed this one from a previous upgrade
docker-compose run --rm api python manage.py script create_actors --no-input
docker-compose run --rm api python manage.py script migrate_to_user_libraries --no-input
On non docker-setups::
# if you missed this one from a previous upgrade
sudo -u funkwhale -H -E /srv/funkwhale/virtualenv/bin/python api/manage.py script create_actors --no-input
sudo -u funkwhale -H -E /srv/funkwhale/virtualenv/bin/python api/manage.py script migrate_to_user_libraries --no-input
If the scripts complete without errors, your instance should be updated and ready to use :)
.. note::
If you use nginx, ensure your funkwhale_proxy.conf file does not contain this:
proxy_set_header X-Forwarded-Host $host:$server_port;
If you have this line present, replace it with:
proxy_set_header X-Forwarded-Host $host;
And reload your nginx server.
docs/admin/backup.rst deleted 100644 → 0
+ 0
− 79
View file @ f0857ae5
Backup your Funkwhale instance
==============================
.. note::
Before upgrading your instance, we strongly advise you to make at least a database backup. Ideally, you should make a full backup, including the database and the media files.
Docker setup
------------
If you've followed the setup instructions in :doc:`../installation/docker`, here is the backup path:
Multi-container installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Backup the database
^^^^^^^^^^^^^^^^^^^
On docker setups, you have to ``pg_dumpall`` in container ``funkwhale_postgres_1``:
.. code-block:: shell
docker exec -t funkwhale_postgres_1 pg_dumpall -c -U postgres > dump_`date +%d-%m-%Y"_"%H_%M_%S`.sql
Backup the media files
^^^^^^^^^^^^^^^^^^^^^^
To backup docker data volumes, as the volumes are bound mounted to the host, the ``rsync`` way would go like this:
.. code-block:: shell
rsync -avzhP /srv/funkwhale/data/media /path/to/your/backup/media
rsync -avzhP /srv/funkwhale/data/music /path/to/your/backup/music
Backup the configuration files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
On docker setups, the configuration file is located at the root level:
.. code-block:: shell
rsync -avzhP /srv/funkwhale/.env /path/to/your/backup/.env
Non-docker setup
----------------
Backup the database
^^^^^^^^^^^^^^^^^^^
On non-docker setups, you have to ``pg_dump`` as user ``postgres``:
.. code-block:: shell
sudo -u postgres -H pg_dump funkwhale > /path/to/your/backup/dump_`date +%d-%m-%Y"_"%H_%M_%S`.sql
Backup the media files
^^^^^^^^^^^^^^^^^^^^^^
A simple way to backup your media files is to use ``rsync``:
.. code-block:: shell
rsync -avzhP /srv/funkwhale/data/media /path/to/your/backup/media
rsync -avzhP /srv/funkwhale/data/music /path/to/your/backup/music
Backup the configuration files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: shell
rsync -avzhP /srv/funkwhale/config/.env /path/to/your/backup/.env
.. note::
You may also want to backup your proxy configuration file.
For frequent backups, you may want to use deduplication and compression to keep the backup size low. In this case, a tool like ``borg`` will be more appropriate.
docs/admin/commands.rst deleted 100644 → 0
+ 0
− 197
View file @ f0857ae5
Management commands
===================
User management
---------------
It's possible to create, remove and update users directly from the command line.
This feature is useful if you want to experiment, automate or perform batch actions that
would be too repetitive through the web UI.
All users-related commands are available under the ``python manage.py fw users`` namespace:
.. code-block:: sh
# print subcommands and help
python manage.py fw users --help
Creation
^^^^^^^^
.. code-block:: sh
# print help
python manage.py fw users create --help
# create a user interactively
python manage.py fw users create
# create a user with a random password
python manage.py fw users create --username alice --email alice@email.host -p ""
# create a user with password set from an environment variable
export FUNKWHALE_CLI_USER_PASSWORD=securepassword
python manage.py fw users create --username bob --email bob@email.host
Additional options are available to further configure the user during creation, such as
setting permissions or user quota. Please refer to the command help.
Update
^^^^^^
.. code-block:: sh
# print help
python manage.py fw users set --help
# set upload quota to 500MB for alice
python manage.py fw users set --upload-quota 500 alice
# disable confirmation prompt with --no-input
python manage.py fw users set --no-input --upload-quota 500 alice
# make alice and bob staff members
python manage.py fw users set --staff --superuser alice bob
# remove staff privileges from bob
python manage.py fw users set --no-staff --no-superuser bob
# give bob moderation permission
python manage.py fw users set --permission-moderation bob
# reset alice's password
python manage.py fw users set --password "securepassword" alice
# reset bob's password through an environment variable
export FUNKWHALE_CLI_USER_UPDATE_PASSWORD=newsecurepassword
python manage.py fw users set bob
Deletion
^^^^^^^^
.. code-block:: sh
# print help
python manage.py fw users rm --help
# delete bob's account, but keep a reference to their account in the database
# to prevent future signup with the same username
python manage.py fw users rm bob
# delete alice's account, with no confirmation prompt
python manage.py fw users rm --no-input alice
# delete alice and bob accounts, including all reference to their account
# (people will be able to signup again with their usernames)
python manage.py fw users rm --hard alice bob
Pruning library
---------------
Because Funkwhale is a multi-user and federated audio server, we don't delete any artist, album
and track objects in the database when you delete the corresponding files.
This is on purpose, because those objects may be referenced in user playlists, favorites,
listening history or on other instances, or other users could have upload files matching
linked to those entities in their own private libraries.
Therefore, Funkwhale has a really conservative approach and doesn't delete metadata when
audio files are deleted.
This behaviour can be problematic in some situations though, e.g. if you imported
a lot of wrongly tagged files, then deleted the files to reimport them later.
To help with that, we provide a management you can run on the server and that will effectively
prune you library from track, album and artist metadata that is not tied to any file:
.. code-block:: sh
# print help
python manage.py prune_library --help
# prune tracks with no uploads
python manage.py prune_library --tracks
# prune albums with no tracks
python manage.py prune_library --albums
# prune artists with no tracks/albums
python manage.py prune_library --artists
# prune everything (tracks, albums and artists)
python manage.py prune_library --tracks --albums --artists
The ``prune_library`` command will not delete anything by default, and only gives
you an estimate of how many database objects would be affected by the pruning.
Once you have reviewed the output and are comfortable with the changes, you should rerun
the command with the ``--no-dry-run`` flag to disable dry run mode and actually apply
the changes on the database.
.. warning::
Running this command with ``--no-dry-run`` is irreversible. Unless you have a backup,
there will be no way to retrieve the deleted data.
.. note::
The command will exclude tracks that are favorited, included in playlists or listening
history by default. If you want to include those in the pruning process as well,
add the corresponding ``--ignore-favorites``, ``--ignore-playlists`` and ``--ignore-listenings``
flags.
Remove obsolete files from database
-----------------------------------
When importing using the :ref:`in-place method <in-place-import>`, if you move or remove
in-place imported files on disk, Funkwhale will still have a reference to those files and won't
be able to serve them properly.
To help with that, whenever you remove or move files that were previously imported
with the ``--in-place`` flag, you can run the following command::
python manage.py check_inplace_files
This command will loop through all the database objects that reference
an in-place imported file, check that the file is accessible on disk,
or delete the database object if it's not.
Once you have reviewed the output and are comfortable with the changes, you should rerun
the command with the ``--no-dry-run`` flag to disable dry run mode and actually delete the
database objects.
.. warning::
Running this command with ``--no-dry-run`` is irreversible. Unless you have a backup,
there will be no way to retrieve the deleted data.
Adding tags from tracks
-----------------------
By default, genre tags found imported files are associated with the corresponding track.
While you can always associate genre information with an artist or album through the web UI,
it may be tedious to do so by hand for a large number of objects.
We offer a command you can run after an import to do this for you. It will:
1. Find all local artists or albums with no tags
2. Get all the tags associated with the corresponding tracks
3. Associate tags that are found on all tracks to the corresponding artist or album
..note::
A periodic task also runs in the background every few days to perform the same process.
Usage:
.. code-block:: sh
# For albums
python manage.py fw albums add-tags-from-tracks --help
# For artists
python manage.py fw artists add-tags-from-tracks --help
docs/admin/configuration.rst deleted 100644 → 0
+ 0
− 340
View file @ f0857ae5
Instance configuration
======================
General configuration is achieved using two type of settings:
- :ref:`environment variables <environment-variables>` and
- :ref:`instance settings <instance-settings>`.
.. _environment-variables:
Environment variables
---------------------
Those are located in your ``.env`` file, which you should have created
during installation. A full list of available variables is given :ref:`below <environment-variables>`.
Options from this file are heavily commented, and usually target lower level
and technical aspects of your instance, such as database credentials.
.. note::
You should restart all Funkwhale processes when you change the values
on environment variables::
sudo systemctl restart funkwhale.target
.. note::
Some characters are unsafe to use in configuration variables that are URLs,
such as the user and password in the database and SMTP sections.
If those variables contain such characters, they must be urlencoded, for
instance using the following command::
python3 -c 'import urllib.parse; print(urllib.parse.quote_plus("p@ssword"))
See as well https://github.com/joke2k/django-environ#using-unsafe-characters-in-urls
.. _instance-settings:
Instance settings
-----------------
These settings are stored in the 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.
.. note::
If you have any issue with the web application, a management interface is also
available for those settings from :doc:`Django's administration interface <django>`. 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
-----------------------
Pod
^^^
.. autodata:: config.settings.common.FUNKWHALE_HOSTNAME
:annotation:
.. autodata:: config.settings.common.FUNKWHALE_PROTOCOL
Database and redis
^^^^^^^^^^^^^^^^^^
.. autodata:: config.settings.common.DATABASE_URL
:annotation:
.. autodata:: config.settings.common.DB_CONN_MAX_AGE
.. autodata:: config.settings.common.CACHE_URL
:annotation:
.. autodata:: config.settings.common.CELERY_BROKER_URL
:annotation:
Accounts and registration
^^^^^^^^^^^^^^^^^^^^^^^^^
.. autodata:: config.settings.common.ACCOUNT_EMAIL_VERIFICATION_ENFORCE
:annotation:
.. autodata:: config.settings.common.USERS_INVITATION_EXPIRATION_DAYS
:annotation:
.. autodata:: config.settings.common.DISABLE_PASSWORD_VALIDATORS
:annotation:
.. autodata:: config.settings.common.ACCOUNT_USERNAME_BLACKLIST
:annotation:
.. autodata:: config.settings.common.AUTH_LDAP_ENABLED
:annotation:
Media storage and serving
^^^^^^^^^^^^^^^^^^^^^^^^^
.. autodata:: config.settings.common.MEDIA_URL
:annotation: = https://mypod.audio/media/
.. autodata:: config.settings.common.MEDIA_ROOT
:annotation: = /srv/funkwhale/data/media
.. autodata:: config.settings.common.PROXY_MEDIA
:annotation: = true
.. autodata:: config.settings.common.EXTERNAL_MEDIA_PROXY_ENABLED
.. autodata:: config.settings.common.ATTACHMENTS_UNATTACHED_PRUNE_DELAY
:annotation: = true
.. autodata:: config.settings.common.REVERSE_PROXY_TYPE
.. autodata:: config.settings.common.PROTECT_FILES_PATH
Audio acquisition
^^^^^^^^^^^^^^^^^
.. autodata:: config.settings.common.MUSIC_DIRECTORY_PATH
.. autodata:: config.settings.common.MUSIC_DIRECTORY_SERVE_PATH
S3 Storage
^^^^^^^^^^
.. autodata:: config.settings.common.AWS_QUERYSTRING_AUTH
.. autodata:: config.settings.common.AWS_QUERYSTRING_EXPIRE
.. autodata:: config.settings.common.AWS_ACCESS_KEY_ID
.. autodata:: config.settings.common.AWS_SECRET_ACCESS_KEY
.. autodata:: config.settings.common.AWS_STORAGE_BUCKET_NAME
.. autodata:: config.settings.common.AWS_S3_CUSTOM_DOMAIN
.. autodata:: config.settings.common.AWS_S3_ENDPOINT_URL
.. autodata:: config.settings.common.AWS_S3_REGION_NAME
.. autodata:: config.settings.common.AWS_LOCATION
API configuration
^^^^^^^^^^^^^^^^^
.. autodata:: config.settings.common.THROTTLING_ENABLED
.. autodata:: config.settings.common.THROTTLING_RATES
.. autodata:: config.settings.common.ADMIN_URL
.. autodata:: config.settings.common.EXTERNAL_REQUESTS_VERIFY_SSL
.. autodata:: config.settings.common.EXTERNAL_REQUESTS_TIMEOUT
Federation
^^^^^^^^^^
.. autodata:: config.settings.common.FEDERATION_OBJECT_FETCH_DELAY
.. autodata:: config.settings.common.FEDERATION_DUPLICATE_FETCH_DELAY
Metadata
^^^^^^^^
.. autodata:: config.settings.common.TAGS_MAX_BY_OBJ
.. autodata:: config.settings.common.MUSICBRAINZ_HOSTNAME
.. autodata:: config.settings.common.MUSICBRAINZ_CACHE_DURATION
Channels and podcasts
^^^^^^^^^^^^^^^^^^^^^
.. autodata:: config.settings.common.PODCASTS_RSS_FEED_REFRESH_DELAY
.. autodata:: config.settings.common.PODCASTS_RSS_FEED_MAX_ITEMS
.. autodata:: config.settings.common.PODCASTS_THIRD_PARTY_VISIBILITY
Subsonic
^^^^^^^^
.. autodata:: config.settings.common.SUBSONIC_DEFAULT_TRANSCODING_FORMAT
Email configuration
^^^^^^^^^^^^^^^^^^^
.. autodata:: config.settings.common.EMAIL_CONFIG
:annotation: = consolemail://
.. autodata:: config.settings.common.DEFAULT_FROM_EMAIL
:annotation: = Funkwhale <noreply@yourdomain>
.. autodata:: config.settings.common.EMAIL_SUBJECT_PREFIX
Other settings
^^^^^^^^^^^^^^
.. autodata:: config.settings.common.INSTANCE_SUPPORT_MESSAGE_DELAY
.. autodata:: config.settings.common.FUNKWHALE_SUPPORT_MESSAGE_DELAY
.. autodata:: config.settings.common.MIN_DELAY_BETWEEN_DOWNLOADS_COUNT
.. autodata:: config.settings.common.MARKDOWN_EXTENSIONS
.. autodata:: config.settings.common.LINKIFIER_SUPPORTED_TLDS
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 responsibility,
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 :ref:`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 instances.
There is no dedicated interface to manage users permissions, but superusers
can login on the :doc:`Django's admin <django>` at ``/api/admin/`` and grant permissions
to users at ``/api/admin/users/user/``.
Front-end settings
------------------
We offer a basic mechanism to customize the behavior and look and feel of Funkwhale's Web UI.
To use any of the options below, you will need to create a custom JSON configuration file and serve it
on ``https://yourinstanceurl/settings.json``.
On typical deployments, this url returns a 404 error, which is simply ignored.
Set-up
^^^^^^
First, create the settings file:
.. code-block:: shell
cd /srv/funkwhale/
# create a directory for your configuration file
# you can use a different name / path of course
mkdir custom
# populate the configuration file with default values
cat <<EOF > custom/settings.json
{
"additionalStylesheets": [],
"defaultServerUrl": null
}
EOF
Once the ``settings.json`` file is created, you will need to serve it from your reverse proxy.
If you are using nginx, add the following snippet to your vhost configuration::
location /settings.json {
alias /srv/funkwhale/custom/settings.json;
}
On Apache, add the following to your vhost configuration::
Alias /settings.json /srv/funkwhale/custom/settings.json
Then, reload your reverse proxy.
At this point, visiting ``https://yourinstanceurl/settings.json`` should serve the content
of the settings.json file.
.. warning::
The settings.json file must be a valid JSON file. If you have any issue, try linting
the file with a tool such as `<https://github.com/zaach/jsonlint>`_ to detect potential
syntax issues.
Available configuration options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Your :file:`settings.json` can contain the following options:
+----------------------------------+--------------------+---------------------------------------+---------------------------------------------------------------+
| Name | Type | Example value | Description |
+----------------------------------+--------------------+---------------------------------------+---------------------------------------------------------------+
| ``additionalStylesheets`` | Array of URLs | ``["https://test/theme.css"]`` | A list of stylesheets URL (absolute or relative) |
| | | (default: ``[]``) | that the web UI should load. see the "Theming" section |
| | | | below for a detailed explanation |
| | | | |
+----------------------------------+--------------------+---------------------------------------+---------------------------------------------------------------+
| ``defaultServerUrl`` | URL | ``"https://api.yourdomain.com"`` | The URL of the API server this front-end should |
| | | (default: ``null``) | connect with. If null, the UI will use |
| | | | the value of VUE_APP_INSTANCE_URL |
| | | | (specified during build) or fallback to the current domain |
+----------------------------------+--------------------+---------------------------------------+---------------------------------------------------------------+
Missing options or options with a ``null`` value in the ``settings.json`` file are ignored.
Theming
^^^^^^^
To theme your Funkwhale instance, you need:
1. A CSS file for your theme, that can be loaded by the front-end;
2. To update the value of ``additionalStylesheets`` in your settings.json file to point to your CSS file URL.
.. code-block:: shell
cd /srv/funkwhale/custom
nano settings.json
# append
# "additionalStylesheets": ["/front/custom/custom.css"]
# to the configuration or replace the existing value, if any
# create a basic theming file changing the background to red
cat <<EOF > custom.css
body {
background-color: red;
}
EOF
The last step to make this work is to ensure your CSS file is served by the reverse proxy.
On nginx, add the following snippet to your vhost config::
location /custom {
alias /srv/funkwhale/custom;
}
On Apache, use the following::
Alias /custom /srv/funkwhale/custom
<Directory "/srv/funkwhale/custom">
Options FollowSymLinks
AllowOverride None
Require all granted
</Directory>
Once done, reload your reverse proxy, refresh Funkwhale in your web browser, and you should see
a red background.
.. note::
You can reference external urls as well in ``additionalStylesheets``, simply use
the full urls. Be especially careful with external urls as they may affect your users
privacy.
.. warning::
Loading additional stylesheets and CSS rules can affect the performance and
usability of your instance. If you encounter issues with the interfaces and use
custom stylesheets, try to disable those to ensure the issue is not caused
by your customizations.
docs/admin/debugging.rst deleted 100644 → 0
+ 0
− 50
View file @ f0857ae5
Debugging Funkwhale
===================
In order to track down errors its useful to provide as many information as possible. Usually pasting
the logs should be sufficient, but there are some tools for some deeper debugging.
Frontend Logs
-------------
Logs and errors written by the Frontend can be accessed with Firefox. When opening the website of
your Funkwhale instance, simply hit ``Ctlr + Shift + J``. Alternatively open the Firefox Menu and open
the Browser Console in the developers menu.
In the opening window you can see all the output. You can copy what you want to share or repeat the
failing operation to see what error occurs.
Backend Logs
------------
Depending on your setup you can see the logs from our API server in different ways.
Docker
^^^^^^
Simply run ``docker-compose logs --tail=100 api`` If you want continuous logs, add the ``f`` flag.
Quick install
^^^^^^^^^^^^^
To get the logs, run ``journalctl -xn -u funkwhale-server``
Profiling
---------
In order to find performance issues, its possible to run API requests with activated profiling. In
order to do this, add ``funkwhale_api.common.middleware.ProfilerMiddleware`` to the environment
variable ``ADDITIONAL_MIDDLEWARES_BEFORE``
If enabled, simply add ``?prof`` to the request URL you want to profile. You should get an HTML-Report
of the running request.
Memory Tracing
--------------
Its possible to print memory traces for each API request to the API logs. In order to do this, add
``funkwhale_api.common.middleware.PymallocMiddleware`` to the environment variable
``ADDITIONAL_MODDLEWARES_BEFORE`` This adds a middleware which should not do anything by default.
Tracing can be activated by setting ``PYTHONTRACEMALLOC=1`` This might has some inpact on the
performance, please report how it goes. The Middleware now prints the top 25 memory allocations to
the API logs.
docs/admin/django.rst deleted 100644 → 0
+ 0
− 79
View file @ f0857ae5
Using the Django Administration Backend
=======================================
Funkwhale is being actively developed, and new features are being added to the frontend all the time. However, there are some administrative tasks that can only be undertaken in the Django Administration backend.
.. Warning::
Deleting items on the backend is **not** recommended. Deletions performed on the backend are permanent. If you remove something in the backend, you will need to re-add it from scratch.
Accessing the Django Backend
----------------------------
To access your instance's backend, navigate to ``https://yourdomain/api/admin``. You will be prompted to log in. By default, the login details will be those of the priviliged user created during the setup process.
Deleting Items
-------------------
By default, deleting items in the front end removes the file from the server but **does not** delete associated entities such as artists, albums, and track data, meaning that they will still be viewable but no longer playable. Items deleted in this way will also still count on the instance statistics. To remove them completely, it is necessary to remove them from the database entirely using the Django Administration backend.
.. Warning::
Deleting tracks, albums, or artists will also remove them completely from any associated playlists, radios, or favorites lists. Before continuing, make sure other users on the instance are aware of the deletion(s).
Deleting a Track
^^^^^^^^^^^^^^^^
* Navigate to ``https://yourdomain/api/admin/music/track``
* Select the track(s) you wish to delete
* In the ``Action`` dropdown menu, select "Delete Selected Items"
* Click on "Go". You will be prompted to confirm the track's deletion
Deleting an Album
^^^^^^^^^^^^^^^^^
* Navigate to ``https://yourdomain/api/admin/music/album``
* Select the album(s) you wish to delete
* In the ``Action`` dropdown menu, select "Delete Selected Items"
* Click on "Go". You will be prompted to confirm the album's deletion
.. note::
Deleting an album will remove all tracks associated with the album
Deleting an Artist
^^^^^^^^^^^^^^^^^^
* Navigate to ``https://yourdomain/api/admin/music/artist``
* Select the artist(s) you wish to delete
* In the ``Action`` dropdown menu, select "Delete Selected Items"
* Click on "Go". You will be prompted to confirm the artist's deletion
.. note::
Deleting an artist will remove all tracks and albums associated with the artist
Removing a Followed Library
---------------------------
In Funkwhale, unfollowing a library will leave the items in place but inaccessible. To completely remove them:
* Navigate to ``https://yourdomain/api/admin/music/library/``
* Tick the box next to the library you wish to remove
* In the ``Action`` dropdown menu, select "Delete Selected Items"
* Click on "Go". You will be prompted to confirm the library's deletion
Adding Missing Album Art
-------------------------
Sometimes album art can fail to appear despite music being properly tagged. When this happens, it is possible to replace the missing art.
* Navigate to ``https://yourdomain/api/admin/music/album``
* Search for and select the album in question
* Find the item marked "Cover"
* Click "Browse" and select the file from your computer
* Click "Save" to confirm the changes
The album art will now be present on the frontend.
.. note::
You can also clear currently loaded album art by checking the checkbox next to the current item and selecting "Clear"
docs/admin/external-storages.rst deleted 100644 → 0
+ 0
− 206
View file @ f0857ae5
Using external storages to store Funkwhale content
==================================================
By default, Funkwhale will store user-uploaded and related media such as audio files,
transcoded files, avatars and album covers on a server directory.
However, for bigger instances or more complex deployment scenarios, you may want
to use distributed or external storages.
S3 and S3-compatible servers
----------------------------
.. note::
This feature was released in Funkwhale 0.19 and is still considered experimental.
Please let us know if you see anything unusual while using it.
Funkwhale supports storing media files Amazon S3 and compatible implementations such as Minio or Wasabi.
In this scenario, the content itself is stored in the S3 bucket. Non-sensitive media such as
album covers or user avatars are served directly from the bucket. However, audio files
are still served by the reverse proxy, to enforce proper authentication.
To enable S3 on Funkwhale, add the following environment variables::
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_STORAGE_BUCKET_NAME=
# An optional bucket subdirectory were you want to store the files. This is especially useful
# if you plan to use share the bucket with other services
# AWS_LOCATION=
# If you use a S3-compatible storage such as minio, set the following variable
# the full URL to the storage server. Example:
# AWS_S3_ENDPOINT_URL=https://minio.mydomain.com
# AWS_S3_ENDPOINT_URL=
Then, edit your nginx configuration. On docker setups, the file is located at ``/srv/funkwhale/nginx/funkwhale.template``,
and at ``/etc/nginx/sites-available/funkwhale.template`` on non-docker setups.
Replace the ``location /_protected/media`` block with the following::
location ~ /_protected/media/(.+) {
internal;
# Needed to ensure DSub auth isn't forwarded to S3/Minio, see #932
proxy_set_header Authorization "";
proxy_pass $1;
}
Add your S3 store URL to the ``img-src`` and ``media-src`` headers
.. code-block:: shell
add_header Content-Security-Policy "...img-src 'self' https://<your-s3-URL> data:;...media-src https://<your-s3-URL> 'self' data:";
Then restart Funkwhale and nginx.
From now on, media files will be stored on the S3 bucket you configured. If you already
had media files before configuring the S3 bucket, you also have to move those on the bucket
by hand (which is outside the scope of this guide).
.. note::
At the moment, we do not support S3 when using Apache as a reverse proxy.
.. note::
If you are attempting to integrate your docker deployment with an existing nginx webserver,
such as the one provided by `linuxserver/swag <https://docs.linuxserver.io/images/docker-swag>`_
(formerly `linuxserver/letsencrypt <https://docs.linuxserver.io/images/docker-swag#migrating-from-the-old-linuxserver-letsencrypt-image>`_),
you may run into an issue where an additional ``Content-Security-Policy`` header appears in responses from the server,
without the newly included S3 URL values.
In this case, you can suppress the extraneous ``Content-Security-Policy`` header by specifying it in a ``proxy_hide_header``
`directive <http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header>`_ in the ``location /`` block.
.. code-block:: shell
location / {
proxy_pass http://funkwhale:80;
# ...
# ... include the rest of the preset directives
# ...
proxy_hide_header Content-Security-Policy;
}
Serving audio files directly from the bucket
********************************************
Depending on your setup, you may want to serve audio files directly from the S3 bucket
instead of proxying them through Funkwhale, e.g to reduce the bandwidth consumption on your server,
or get better performance.
You can achieve that by adding ``PROXY_MEDIA=false`` to your ``.env`` file.
When receiving a request on the stream endpoint, Funkwhale will check for authentication and permissions,
then issue a 302 redirect to the file URL in the bucket.
This URL is actually be visible by the client, but contains a signature valid only for one hour, to ensure
no one can reuse this URL or share it publicly to distribute unauthorized content.
.. note::
If you are using Amazon S3, you will need to set your ``AWS_S3_REGION_NAME`` in the ``.env`` file to
use this feature.
.. note::
Since some Subsonic clients don't support 302 redirections, Funkwhale will ignore
the ``PROXY_MEDIA`` setting and always proxy file when accessed through the Subsonic API.
Securing your S3 bucket
***********************
It's important to ensure your the root of your bucket doesn't list its content,
which is the default on many S3 servers. Otherwise, anyone could find out the true
URLs of your audio files and bypass authentication.
To avoid that, you can set the following policy on your bucket::
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:GetObject"
],
"Effect": "Allow",
"Principal": {
"AWS": [
"*"
]
},
"Resource": [
"arn:aws:s3:::<yourbucketname>/*"
],
"Sid": "Public"
}
]
}
If you are using ``awscli``, you can store this policy in a ``/tmp/policy`` file, and
apply it using the following command::
aws s3api put-bucket-policy --bucket <yourbucketname> --policy file:///tmp/policy
Troubleshooting
***************
No Resolver Found
^^^^^^^^^^^^^^^^^
Depending on your setup, you may experience the following issue when trying to stream
music directly from your S3-compatible store.
.. code-block:: shell
[error] 2832#2832: *1 no resolver defined to resolve [address] client: [IP], server: [servername], request: "GET API request", host: "[your_domain]", referrer: "[your_domain/library]"
This happpens when the nginx config is unable to use your server's DNS resolver. This issue
is still under investigation, but in the meantime can be worked around by specifying a resolver
in your ``funkwhale.template`` under the ``location ~/_protected/media/(.+)`` section.
.. code-block:: shell
location ~ /_protected/media/(.+) {
resolver 1.1.1.1;
internal;
proxy_set_header Authorization "";
proxy_pass $1;
}
No Images or Media Loading
^^^^^^^^^^^^^^^^^^^^^^^^^^
If you are serving media from an S3-compatible store, you may experience an issue where
nothing loads in the front end. The error logs in your browser may show something like
the following:
.. code-block:: text
Content Security Policy: The page's settings blocked the loading of a resource at https://<your-s3-url> ("img-src")
Content Security Policy: The page's settings blocked the loading of a resource at https://<your-s3-url> ("media-src")
This happens when your S3 store isn't defined in the ``Content-Security-Policy`` headers
in your Nginx files. To resolve the issue, add the base URL of your S3 store to the ``img-src``
and ``media-src`` headers and reload nginx.
.. code-block:: shell
add_header Content-Security-Policy "...img-src 'self' https://<your-s3-URL> data:;...media-src https://<your-s3-URL> 'self' data:";
Broken Images in Audio Player On Page Reload
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you are serving media directly from an S3-compatible store, you may find that images
in the queue and the player won't load after the page is refreshed. This happens if the
generated URL has expired and the authorization is no longer valid. You can extend the expiry time
using the following setting in your ``.env`` file:
.. code-block:: shell
# The default value is 3600 (60 mins). The maximum is 604800 (7 days)
AWS_QUERYSTRING_EXPIRE=604800
docs/admin/importing-music.rst deleted 100644 → 0
+ 0
− 227
View file @ f0857ae5
Importing music from the server
===============================
Funkwhale can import music files saved on the server
assuming they are readable by the Funkwhale application.
Your music files should contain at least
``artist``, ``album`` and ``title`` tags,
but we recommend you tag extensively using a proper tool,
such as Beets or Musicbrainz Picard.
Funkwhale supports two different import modes:
- copy(default): files are copied into Funkwhale's internal storage. This means importing a 1GB library will result in the same amount of space being used by Funkwhale.
- :ref:`in-place <in-place-import>` (with ``--in-place`` flag): files are referenced in Funkwhale's DB but not copied or touched in anyway. This is useful if you have a huge library, or one that is updated by an external tool such as Beets.
Regardless of the mode you choose,
follow the below steps to import music,
assuming your files are located in
``/srv/funkwhale/data/music``:
.. code-block:: bash
export LIBRARY_ID="<your_libary_id>"
python api/manage.py import_files $LIBRARY_ID "/srv/funkwhale/data/music/" --recursive --noinput
.. note::
You have to create a library in the Web UI to get your library ID.
Simply visit https://yourdomain/content/libraries/ to create one.
Library IDs are part of the library url or sharing link.
For example, the library ID of
https://funkwhale.instance/content/libraries/769a2ae3-eb3d-4aff-9f94-2c4d80d5c2d1,
is 769a2bc3-eb1d-4aff-9f84-2c4d80d5c2d1
You can use only the first characters of the ID when calling the command, like that:
``export LIBRARY_ID="769a2bc3"``
When you use docker, ``/srv/funkwhale/data/music`` is mounted from the host
to the ``/music`` directory on the container:
.. code-block:: bash
export LIBRARY_ID="<your_libary_id>"
docker-compose run --rm api python manage.py import_files $LIBRARY_ID "/music/" --recursive --noinput
When you installed Funkwhale via ansible, you need to call a script instead of Python, and the folder path must be adapted accordingly:
.. code-block:: bash
export LIBRARY_ID="<your_libary_id>"
/srv/funkwhale/manage import_files $LIBRARY_ID "/srv/funkwhale/data/music/" --recursive --noinput
The import command supports several options,
check the help for details::
docker-compose run --rm api python manage.py import_files --help
.. note::
We recommend tagging your music collection using `Picard <http://picard.musicbrainz.org/>`_ to have the best quality metadata.
.. note::
This command is idempotent,
meaning you can run it multiple times on the same files
and already imported files are simply skipped.
.. note::
At the moment, only Flac, OGG/Vorbis and MP3 or AIFF files with ID3 tags are supported.
.. _in-place-import:
In-place import
^^^^^^^^^^^^^^^
By default, the CLI-importer will copy imported files to Funkwhale's internal storage.
This means importing a 1GB library will result
in the same amount of space being used by Funkwhale.
While this behaviour has some benefits (easier backups and configuration),
it is not always the best choice,
especially if you have a huge library to import
and don't want to double your disk usage.
The CLI importer supports an additional ``--in-place`` option
through which Funkwhale will store file paths rather than file content.
Structure
*********
Because imported files are not managed by Funkwhale,
we offer additional configuration options
to ensure the webserver can serve them properly:
- :data:`MUSIC_DIRECTORY_PATH <config.settings.common.MUSIC_DIRECTORY_PATH>`
- :data:`MUSIC_DIRECTORY_SERVING_PATH <config.settings.common.MUSIC_DIRECTORY_SERVE_PATH>`
We recommend you symlink all your music directories into ``/srv/funkwhale/data/music``
and run the `import_files` command from that directory.
This will make it possible to use multiple music directories
without any additional configuration on the webserver side.
For instance, if you have an NFS share
with your music mounted at ``/media/mynfsshare``,
you can create a symlink like this::
ln -s /media/mynfsshare /srv/funkwhale/data/music/nfsshare
And import music from the share::
export LIBRARY_ID="<your_libary_id>"
python api/manage.py import_files $LIBRARY_ID "/srv/funkwhale/data/music/nfsshare/" --recursive --noinput --in-place
Docker
******
Docker setups require a bit more work,
because while the ``/srv/funkwhale/data/music`` is mounted in containers,
symlinked directories are not.
To fix that, you can use bind mounts instead of symbolic links,
as they replicate the source directory tree.
With the previous NFS share, use this command::
mount --bind /media/mynfsshare /srv/funkwhale/data/music/nfsshare
If you want to go with symlinks,
ensure each symlinked directory is mounted as a volume
as well as in your ``docker-compose.yml`` file::
celeryworker:
volumes:
- ./data/music:/music:ro
- ./data/media:/app/funkwhale_api/media
# add your symlinked dirs here
- /media/nfsshare:/media/nfsshare:ro
api:
volumes:
- ./data/music:/music:ro
- ./data/media:/app/funkwhale_api/media
# add your symlinked dirs here
- /media/nfsshare:/media/nfsshare:ro
Metadata updates
^^^^^^^^^^^^^^^^
When doing an import with in ``in-place`` mode,
the importer will also check and update existing entries found in the database.
For instance, if the ID3 Title tag of an existing song was updated since the last scan, Funkwhale picks up the new title.
The following fields can be updated this way:
- Track mbid
- Track title
- Track position and disc number
- Track license and copyright
- Track genre (`from version 1.2 <https://dev.funkwhale.audio/funkwhale/funkwhale/-/merge_requests/1225>`_)
- Album cover
- Album title
- Album mbid
- Album release date
- Artist name
- Artist mbid
- Album artist name
- Album artist mbid
Changes in artist name can lead to multiple artists with the same name in the database,
`this is a known issue <https://dev.funkwhale.audio/funkwhale/funkwhale/-/issues/1318>`_
and can be remedied by adding mbids.
React to filesystem events with ``--watch``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you have a really big library or update it regularly,
running the ``import_files`` command by hand may not be practical.
For this use case,
the ``import_files`` command supports a ``--watch`` flag
through which it observes filesystem events instead of performing a full import.
File creation, move, update and removal
are handled when ``--watch`` is provided:
- Files created in the watched directory are imported immediately
- If using ``in-place`` mode, files updates trigger a metadata update on the corresponding entries
- If using ``in-place`` mode, files that are moved and known by Funkwhale will see their path updated in Funkwhale's DB
- If using ``in-place`` mode, files that are removed and known by Funkwhale will be removed from Funkwhale's DB
Pruning dangling metadata with ``--prune``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Funkwhale is, by design, conservative with music metadata in its database.
If you remove a file from Funkwhale's DB,
the corresponding artist, album and track object won't be deleted by default.
If you want to prune dangling metadata from the database once the ``import_files`` command is over, simply add the ``--prune`` flag.
This also works in with ``--watch``.
Album covers
^^^^^^^^^^^^
Whenever possible, Funkwhale obtains album covers for tracks,
with the following precedence:
1. The cover embedded in the audio files themeselves, if any (Flac/MP3 only)
2. Use a cover.jpg or a cover.png file from the imported track directory, if any
3. Fetch cover art from musicbrainz, assuming the file is tagged correctly
Getting demo tracks
^^^^^^^^^^^^^^^^^^^
If you do not have any music on your server
but want to test the import process,
you can call the following methods
to download a few albums licenced under creative commons (courtesy of Jamendo):
.. parsed-literal::
curl -L -o download-tracks.sh "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/demo/download-tracks.sh"
curl -L -o music.txt "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/demo/music.txt"
chmod +x download-tracks.sh
./download-tracks.sh music.txt
This will download a bunch of zip archives (one per album)
under the ``data/music`` directory and unzip their content.
docs/admin/index.rst deleted 100644 → 0
+ 0
− 43
View file @ f0857ae5
Administrator Documentation
=====================================
This documentation is targeted at administrators of instances. This typically refers to
the person(s) responsible for running the server and managing the software on a technical
level.
Setup Guides
------------
.. toctree::
:maxdepth: 2
../installation/index
configuration
importing-music
external-storages
optimization
backup
migration
uninstall
ldap
Administration
--------------
.. toctree::
:maxdepth: 2
django
commands
url
upgrading
mrf
Troubleshooting
---------------
.. toctree::
:maxdepth: 2
troubleshooting
debugging
docs/admin/ldap.rst deleted 100644 → 0
+ 0
− 43
View file @ f0857ae5
LDAP configuration
==================
LDAP is a protocol for providing directory services, in practice allowing a central authority for user login information.
Funkwhale supports LDAP through the Django LDAP authentication module and by setting several configuration options.
.. warning::
Note that LDAP-based users cannot change their password inside the app.
Dependencies
------------
LDAP support requires some additional dependencies to enable. On the OS level both ``libldap2-dev`` and ``libsasl2-dev`` are required, and the Python modules ``python-ldap`` and ``python-django-auth-ldap`` must be installed. These dependencies are all included in the ``requirements.*`` files so deploying with those will install these dependencies by default. However, they are not required unless LDAP support is explicitly enabled.
Environment variables
---------------------
LDAP authentication is configured entirely through the environment variables. The following options enable the LDAP features:
Basic features
^^^^^^^^^^^^^^
- ``LDAP_ENABLED``: Set to ``True`` to enable LDAP support. Default: ``False``.
- ``LDAP_SERVER_URI``: LDAP URI to the authentication server, e.g. ``ldap://my.host:389``.
- ``LDAP_BIND_DN``: LDAP user DN to bind as to perform searches.
- ``LDAP_BIND_PASSWORD``: LDAP user password for bind DN.
- ``LDAP_SEARCH_FILTER``: The LDAP user filter, using ``{0}`` as the username placeholder, e.g. ``(|(cn={0})(mail={0}))``; uses standard LDAP search syntax. Default: ``(uid={0})``.
- ``LDAP_START_TLS``: Set to ``True`` to enable LDAP StartTLS support. Default: ``False``.
- ``LDAP_ROOT_DN``: The LDAP search root DN, e.g. ``dc=my,dc=domain,dc=com``; supports multiple entries in a space-delimited list, e.g. ``dc=users,dc=domain,dc=com dc=admins,dc=domain,dc=com``.
- ``LDAP_USER_ATTR_MAP``: A mapping of Django user attributes to LDAP values, e.g. ``first_name:givenName, last_name:sn, username:cn, email:mail``. Default: ``first_name:givenName, last_name:sn, username:cn, email:mail``.
- ``AUTH_LDAP_BIND_AS_AUTHENTICATING_USER``: Controls whether direct binding is used. Default: ``False``.
Group features
^^^^^^^^^^^^^^
For details on these options, see the `Django documentation <https://django-auth-ldap.readthedocs.io/en/latest/groups.html>`_. Group configuration is disabled unless an ``LDAP_GROUP_DN`` is set. This is an advanced LDAP feature and most users should not need to configure these settings.
- ``LDAP_GROUP_DN``: The LDAP group search root DN, e.g. ``ou=groups,dc=domain,dc=com``.
- ``LDAP_GROUP_FILTER``: The LDAP group filter, e.g. ``(objectClass=groupOfNames)``.
- ``LDAP_REQUIRE_GROUP``: A group users must be a part of to authenticate, e.g. ``cn=enabled,ou=groups,dc=domain,dc=com``.
- ``LDAP_DENY_GROUP``: A group users must not be a part of to authenticate, e.g. ``cn=disabled,ou=groups,dc=domain,dc=com``.
docs/admin/migration.rst deleted 100644 → 0
+ 0
− 113
View file @ f0857ae5
Migrating to a New Server
=========================
Sometimes, it may be necessary or desirable to migrate your
existing Funkwhale setup to a new server. This can be helpful
if you need to boost resources or if you wish to use a different
hosting platform.
In this guide, the existing Funkwhale setup is called the origin server, and the new setup the destination server.
Requirements
------------
To get started with your new setup, you will need to have the
following:
- `rsync <https://linux.die.net/man/1/rsync>`_ installed on the **destination** server
- SSH access set up between the two servers
Non-Docker
----------
On the destination server, run through the :doc:`installation steps<../installation/debian>` with the exception of the following points:
- Do not enable the extensions ``unaccent`` and ``citext`` when setting up the database;
- Do not initialize the database by applying the migrate command;
- Do not create an admin account.
Stop all funkwhale related services on the destination server:
.. code-block:: shell
sudo systemctl stop funkwhale.target
On the origin server, create a database backup:
.. code-block:: shell
sudo -u funkwhale pg_dump -d funkwhale > "db.dump"
On the destination server, use rsync to fetch the contents of ``/srv/funwkhale/data/media/music/`` and ``/srv/funkwhale/data/media/`` from the origin server, as well as the database dump and the ``.env`` file:
.. code-block:: shell
origin = <origin server IP/hostname>
username = <your username>
rsync -a $username@$origin:/srv/funkwhale/data/media/ /srv/funkwhale/data/media/
rsync -a $username@$origin:/srv/funkwhale/data/music/ /srv/funkwhale/data/music/
rsync -a $username@$origin:/srv/funkwhale/config/.env /srv/funkwhale/config/
rsync -a $username@$origin:/srv/funkwhale/db.dump /srv/funkwhale/
On the destination server, restore the database dump:
.. code-block:: shell
sudo psql -d funkwhale db.dump
Once the database has been restored, follow the database migration steps from the non-docker installation guide to complete the installation on the destination server.
Ensure that all DNS changes have been made and start the services:
.. code-block:: shell
sudo systemctl start funkwhale.target
Docker
------
On the destination server, run through the :doc:`installation steps<../installation/docker>` but skip the ``docker-compose run --rm api python manage.py migrate`` step.
Stop all funkwhale related containers on the destination server.
On the origin server, create a database backup:
.. code-block:: shell
docker exec -t funkwhale_postgres_1 pg_dumpall -c -U postgres > "db.dump"
On the destination server, use rsync to fetch the contents of ``/srv/funwkhale/data/media/music`` and ``/srv/funkwhale/data/media`` from the origin server, as well as the database dump nd the ``.env`` file:
.. code-block:: shell
origin = <origin server IP/hostname>
username = <your username>
rsync -a $username@$origin:/srv/funkwhale/data/media/ /srv/funkwhale/data/media/
rsync -a $username@$origin:/srv/funkwhale/data/music/ /srv/funkwhale/data/music/
rsync -a $username@$origin:/srv/funkwhale/.env /srv/funkwhale/
rsync -a $username@$origin:/srv/funkwhale/db.dump /srv/funkwhale/
Initialize the Postgres container with the funkwhale database and its user. For easier, we create a db init dump file than we import in the postgres container:
.. code-block:: shell
echo "CREATE DATABASE "funkwhale"
WITH ENCODING 'utf8';
CREATE USER funkwhale;
GRANT ALL PRIVILEGES ON DATABASE funkwhale TO funkwhale;" > init.dump
docker exec -i funkwhale_postgres_1 psql -U postgres -d postgres < "init.dump"
After that, we can restore the database dump:
.. code-block:: shell
docker exec -i funkwhale_postgres_1 psql -U postgres -d postgres < "db.dump"
Once the database has been restored, run the migrations following the docker installation guide.
Ensure that all DNS changes have been made and start the services.
docs/admin/mrf.rst deleted 100644 → 0
+ 0
− 117
View file @ f0857ae5
Message Rewrite Facility (MRF)
==============================
Funkwhale includes a feature that mimics `Pleroma's Message Rewrite Facility <https://docs-develop.pleroma.social/backend/configuration/mrf/>`_.
Using the MRF, instance admins can write and configure custom and automated moderation rules
that couldn't be implemented otherwise using :doc:`our other built-in moderation tools <../moderator/index>`.
Architecture
------------
The MRF is a pluggable system that will process messages and forward those to the list
of registered policies, in turn. Each policy can mutate the message, leave it as is, or discard it entirely.
Some of our built-in moderation tools are actually implemented as a MRF policy, e.g:
- Allow-list, when checking incoming messages (`code <https://dev.funkwhale.audio/funkwhale/funkwhale/blob/develop/api/funkwhale_api/moderation/mrf_policies.py>`__)
- Domain and user blocking, when checking incoming messages (`code <https://dev.funkwhale.audio/funkwhale/funkwhale/blob/develop/api/funkwhale_api/federation/mrf_policies.py>`__)
.. note::
While Pleroma MRF policies can also affect outgoing messages, this is not supported yet in Funkwhale.
Disclaimer
----------
Writing custom MRF can impact negatively the performance and stability of your pod, as well as message
delivery. Your policy will be called everytime a message is delivered, so ensure you don't execute
any slow operation here.
Please note that the Funkwhale developers consider custom MRF policy modules to fall under the purview of the AGPL. As such, you are obligated to release the sources to your custom MRF policy modules upon request.
Writing your first MRF policy
-----------------------------
MRF Policies are written as Python 3 functions that take at least one ``payload`` parameter.
This payload is the raw ActivityPub message, received via HTTP, after the HTTP signature check.
In the example below we write a policy that discards all Follow requests from listed domains:
.. code-block:: python
import urllib.parse
from funkwhale_api.moderation import mrf
BLOCKED_FOLLOW_DOMAINS = ['domain1.com', 'botdomain.org']
# registering the policy is required to have it applied
# the name can be anything you want, it will appear in the mrf logs
@mrf.inbox.register(name='blocked_follow_domains')
def blocked_follow_domains_policy(payload, **kwargs):
actor_id = payload.get('actor')
domain = urllib.parse.urlparse(actor_id).hostname
if domain not in BLOCKED_FOLLOW_DOMAINS:
# raising mrf.Skip isn't strictly necessary but it provides
# for info in the debug logs. Otherwise, you can simply return
raise mrf.Skip("This domain isn't blocked")
activity_type = payload.get('type')
object_type = payload.get('object', {}).get('type')
if object_type == 'Follow' and activity_type == 'Create':
raise mrf.Discard('Follow from blocked domain')
This code must be stored in a Funkwhale plugin. To create one, just execute the following:
.. code-block:: shell
# plugin name must contain only ASCII letters, numbers and undercores
export PLUGIN_NAME="myplugin"
# this is the default path where Funkwhale will look for plugins
# if you want to use another path, update this path and ensure
# your PLUGINS_PATH is also included in your .env
export PLUGINS_PATH="/srv/funkwhale/plugins/"
mkdir -p $PLUGINS_PATH/$PLUGIN_NAME
cd $PLUGINS_PATH/$PLUGIN_NAME
touch __init__.py # required to make the plugin a valid Python package
# create the required apps.py file to register our plugin in Funkwhale
cat > apps.py <<EOF
from django.apps import AppConfig
class Plugin(AppConfig):
name = "$PLUGIN_NAME"
EOF
Once you have a Funkwhale plugin, simply put your MRF policy code inside a ``mrf_policies.py``
file whithin the plugin directory. Then enable the plugin in your ``.env`` by
adding its name to the coma-separated list of ``FUNKWHALE_PLUGINS`` (add the variable if it's not there).
Testing a MRF policy
--------------------
To make the job of writing and debugging MRF policies easier, we provide a management
command:
.. code-block:: shell
python manage.py mrf_check --help
# list registered MRF policies
python manage.py mrf_check --list
# check how our MRF would handle a legit follow
export MRF_MESSAGE='{"actor": "https://normal.domain/@alice", "type": "Create", "object": {"type": "Follow"}}'
echo $MRF_MESSAGE | python manage.py mrf_check inbox - -p blocked_follow_domains
# check how our MRF would handle a problematic follow
export MRF_MESSAGE='{"actor": "https://botdomain.org/@bob", "type": "Create", "object": {"type": "Follow"}}'
echo $MRF_MESSAGE | python manage.py mrf_check inbox - -p blocked_follow_domains
# check against an activity already present in the database
# you can get the UUID of activities by visiting /api/admin/federation/activity
export ACTIVITY_UUID="06208aea-c687-4e8b-aefd-22f1c3f76039"
echo $MRF_MESSAGE | python manage.py mrf_check inbox $ACTIVITY_UUID -p blocked_follow_domains
docs/admin/optimization.rst deleted 100644 → 0
+ 0
− 37
View file @ f0857ae5
Optimizing your Funkwhale instance
==================================
Depending on your requirements, you may want to reduce as much as possible
Funkwhale's memory footprint.
Reduce workers concurrency
--------------------------
Asynchronous tasks are handled by a celery worker, which will by default
spawn a worker process per CPU available. This can lead to a higher
memory usage.
You can control this behavior using the ``--concurrency`` flag.
For instance, setting ``--concurrency=1`` will spawn only one worker.
This flag should be appended after the ``celery -A funkwhale_api.taskapp
worker`` command in your :file:`docker-compose.yml` file if your using Docker,
or in your :file:`/etc/systemd/system/funkwhale-worker.service` otherwise.
.. note::
Reducing concurrency comes at a cost: asynchronous tasks will be processed
more slowly. However, on small instances, this should not be an issue.
Switch from prefork to solo pool
--------------------------------
Using a different pool implementation for Celery tasks may also help.
Using the ``solo`` pool type should reduce your memory consumption.
You can control this behavior using the ``--pool=solo`` flag.
This flag should be appended after the ``celery -A funkwhale_api.taskapp worker``
command in your :file:`docker-compose.yml` file if you're using Docker, or in
your :file:`/etc/systemd/system/funkwhale-worker.service` otherwise.
docs/admin/troubleshooting.rst deleted 100644 → 0
+ 0
− 169
View file @ f0857ae5
Troubleshooting
===============
Various errors and issues can arise on your Funkwhale instance, caused by configuration errors,
deployment/environment specific issues, or bugs in the software itself.
On this document, you'll find:
- Tools and commands you can use to better understand the issues
- A list of common pitfalls and errors and how to solve them
- A collection of links and advice to get help from the community and report new issues
Diagnose problems
^^^^^^^^^^^^^^^^^
Funkwhale is made of several components, each one being a potential cause for failure. Having an even basic overview
of Funkwhale's technical architecture can help you understand what is going on. You can refer to :doc:`the technical architecture <../developers/architecture>` for that.
Problems usually fall into one of those categories:
- **Frontend**: Funkwhale's interface is not loading, not behaving as expected, music is not playing
- **API**: the interface do not display any data or show errors
- **Import**: uploaded/imported tracks are not imported correctly or at all
- **Federation**: you cannot contact other Funkwhale servers, access their library, play federated tracks
- **Everything else**
Each category comes with its own set of diagnose tools and/or commands we will detail below. We'll also give you simple
steps for each type of problem. Please try those to see if it fix your issues. If none of those works, please report your issue on our
issue tracker.
.. note::
To get detailed log messages, set the environment variable ``LOGLEVEL=debug``.
If you are using the docker setup you can configure this in the ``.env`` file.
Backend issues
^^^^^^^^^^^^^^
Diagnostic tools:
- Reverse proxy logs:
- Apache logs should be available at :file:`/var/log/apache/access.log` and :file:`/var/log/apache/error.log`
- Nginx logs should be available at :file:`/var/log/nginx/access.log` and :file:`/var/log/nginx/error.log`
- API logs:
- Docker setup: ``docker-compose logs -f --tail=50 api`` (remove the ``--tail`` flag to get the full logs)
- Non-docker setup: ``journalctl -xn -u funkwhale-server``
.. note::
If you edit your .env file to test a new configuration, you have to restart your services to pick up the changes:
- Docker setup: ``docker-compose up -d``
- Non-docker setup: ``systemctl restart funkwhale.target``
Common problems
***************
Instance works properly, but audio files are not served (404 error)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- If you're using docker, ensure the ``MEDIA_ROOT`` variable is commented in your env file
- Ensure the ``_protected/media`` block points toward the path where media files are stored (``/srv/funkwhale/data/media``, by default)
- If you're using in-place import, ensure :data:`MUSIC_DIRECTORY_PATH <config.settings.common.MUSIC_DIRECTORY_PATH>`, :data:`MUSIC_DIRECTORY_SERVE_PATH <config.settings.common.MUSIC_DIRECTORY_SERVE_PATH>` and :data:`REVERSE_PROXY_TYPE <config.settings.common.REVERSE_PROXY_TYPE>` are configured properly, and that the files are readable by the webserver
Weakref error when running ``python manage.py <command>``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
On Python <3.6, you may see this kind of errors when running commands like ``python manage.py migrate``::
Exception ignored in: <function WeakValueDictionary.__init__.<locals>.remove at 0x107e7a6a8>
Traceback (most recent call last):
File "/srv/funkwhale/venv/lib/python3.5/weakref.py", line 117, in remove
TypeError: 'NoneType' object is not callable
This is caused by a bug in Python (cf https://github.com/celery/celery/issues/3818), and is not affecting in any way
the command you execute. You can safely ignore this error.
``Your models have changes that are not yet reflected in a migration`` warning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When running ``python manage.py migrate`` (both in docker or non-docker), you may end-up with this::
Operations to perform:
Apply all migrations: account, admin, auth, authtoken, common, contenttypes, dynamic_preferences, favorites, federation, history, music, playlists, radios, requests, sessions, sites, socialaccount, taggit, users
Running migrations:
No migrations to apply.
Your models have changes that are not yet reflected in a migration, and so won't be applied.
Run 'manage.py makemigrations' to make new migrations, and then re-run 'manage.py migrate' to apply them.
This warning can be safely ignored. You should not run the suggested ``manage.py makemigrations`` command.
File import issues
^^^^^^^^^^^^^^^^^^
Unless you are using the CLI to import files, imports are send as tasks in a queue to a celery worker that will process them.
Diagnostic tools:
- Celery worker logs:
- Docker setup: ``docker-compose logs -f --tail=50 celeryworker`` (remove the ``--tail`` flag to get the full logs)
- Non-docker setup: ``journalctl -xn -u funkwhale-worker``
Federation issues
^^^^^^^^^^^^^^^^^
Received federations messages are sent to a dedicated task queue and processed asynchronously by a celery worker.
Diagnostic tools:
- API logs:
- Docker setup: ``docker-compose logs -f --tail=50 api`` (remove the ``--tail`` flag to get the full logs)
- Non-docker setup: ``journalctl -xn -u funkwhale-server``
- Celery worker logs:
- Docker setup: ``docker-compose logs -f --tail=50 celeryworker`` (remove the ``--tail`` flag to get the full logs)
- Non-docker setup: ``journalctl -xn -u funkwhale-worker``
Common problems
***************
I have no access to another instance library
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Check if it works with the demo library (library@demo.funkwhale.audio)
- Check if the remote library received your follow request and approved it
- Trigger a scan via the interface
- Have a look in the celery logs for potential errors during the scan
Other problems
^^^^^^^^^^^^^^
It's a bit hard to give targeted advice about problems that do not fit in the previous categories. However, we can recommend to:
- Try to identify the scope of the issue and reproduce it reliably
- Ensure your instance is configured as detailed in the installation documentation, and if you did not use the default
values, to check what you changed
- To read the .env file carefully, as most of the options are described in the comments
Report an issue or get help
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Well be more than happy to help you to debug installation and configuration issues. The main channel
for receiving support about your Funkwhale installation is the `#funkwhale-troubleshooting:matrix.org <https://matrix.to/#/#funkwhale-troubleshooting:matrix.org>`_ Matrix channel.
Before asking for help, we'd really appreciate if you took the time to go through this document and try to diagnose the problem yourself. But if you don't find
anything relevant or don't have the time, we'll be there for you!
Here are a few recommendations on how to structure and what to include in your help requests:
- Give us as much context as possible about your installation (OS, version, Docker/non-docker, reverse-proxy type, relevant logs and errors, etc.)
- Including screenshots or small gifs or videos can help us considerably when debugging front-end issues
You can also open issues on our `issue tracker <https://dev.funkwhale.audio/funkwhale/funkwhale/issues>`_. Please have a quick look for
similar issues before doing that, and use the issue tracker only to report bugs, suggest enhancements (both in the software and the documentation) or new features.
.. warning::
If you ever need to share screenshots or urls with someone else, ensure those do not include your personal token.
This token is binded to your account and can be used to connect and use your account.
Urls that includes your token looks like: ``https://your.instance/api/v1/uploads/42/serve/?jwt=yoursecrettoken``
Improving this documentation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you feel like something should be improved in this document (and in the documentation in general), feel free to :doc:`contribute to the documentation <../documentation/creating>`.
If you're not comfortable contributing or would like to ask somebody else to do it, feel free to :doc:`request a change in documentation <../documentation/identifying>`.
docs/admin/uninstall.rst deleted 100644 → 0
+ 0
− 89
View file @ f0857ae5
Uninstall Funkwhale
===================
The following instructions helps you remove Funkwhale from your server, for instance after migrating to another server, or if you do not want to use Funkwhale anymore.
.. warning::
The following instructions cannot be undone and might result in loss of data. If necessary, please make a backup of your server following the :doc:`backup instructions<backup>`.
Especially, it must be noted that:
- Remote content hosted on an S3 or S3-compatible server will not be removed.
- In place imports will not be removed, provided they are located outside ``/srv/funkwhale/``
.. note::
These instructions apply only for the manual installation on Debian or Arch Linux. It matches the default setup.
First, stop the all funkwhale related services:
.. code-block:: shell
sudo systemctl stop funkwhale.target
Remove the reverse proxy configuration data and reload the reverse proxy.
If you are using nginx:
.. code-block:: shell
sudo rm /etc/nginx/sites-enabled/funkwhale.conf
sudo rm /etc/nginx/sites-available/funkwhale.conf
sudo rm /etc/nginx/funkwhale_proxy.conf
sudo systemctl reload nginx
If you are using Apache2:
.. code-block:: shell
sudo rm /etc/apache2/sites-enabled/funkwhale.conf
sudo rm /etc/apache2/sites-available/funkwhale.conf
sudo service apache2 restart
Remove the systemd services:
.. code-block:: shell
sudo systemctl disable funkwhale-server
sudo systemctl disable funkwhale-worker
sudo systemctl disable funkwhale-beat
sudo rm /etc/systemd/system/funkwhale-server.service
sudo rm /etc/systemd/system/funkwhale-worker.service
sudo rm /etc/systemd/system/funkwhale-beat.service
sudo rm /etc/systemd/system/funkwhale.target
sudo systemctl daemon-reload
sudo systemctl reset-failed
Then, remove the database:
.. code-block:: shell
sudo -u postgres psql -c 'DROP DATABASE funkwhale;'
sudo -u postgres psql -c 'DROP USER funkwhale;'
Finally, remove the user ``funkwhale`` and all funkwhale related data, including the server and the data:
.. code-block:: shell
sudo userdel -r funkwhale
.. warning::
The last command will remove ``/srv/funkwhale/``. On the default setup, this directory contains all user data. Please proceed cautiously!
However, it must be noted that:
- Remote content hosted on an S3 or S3-compatible server will not be removed.
- In place imports will not be removed, provided they are not located in the directory ``/srv/funkwhale/``
.. note::
If relevant, you might also want to:
- remove the SSL certificates;
- remove the corresponding DNS entries.
\ No newline at end of file
docs/admin/upgrading.rst deleted 100644 → 0
+ 0
− 199
View file @ f0857ae5
Upgrading your Funkwhale instance to a newer version
====================================================
.. note::
Before upgrading your instance, we strongly advise you to make at least a database backup. Ideally, you should make a full backup, including
the database and the media files.
We're commited to make upgrade as easy and straightforward as possible,
however, Funkwhale is still in development and you'll be safer with a backup.
Reading the release notes
-------------------------
Please take a few minutes to read the :doc:`../changelog`: updates should work
similarly from version to version, but some of them may require additional steps.
Those steps would be described in the version release notes.
Insights about new versions
---------------------------
Some versions may be bigger than usual, and we'll try to detail the changes
when possible.
.. toctree::
:maxdepth: 1
0.17
Docker setup
------------
If you've followed the setup instructions in :doc:`../installation/docker`, upgrade path is
easy:
Mono-container installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Basically, you need to pull the new container image, stop and delete your existing container,
and relaunch a new one:
To upgrade your service, change the version number of the image in ``docker-compose.yml`` with the latest release (i.e. |version|).
Pull the new images:
.. code-block:: shell
docker-compose pull
Restart the service:
.. code-block:: shell
docker-compose up -d
Multi-container installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. parsed-literal::
# this assumes you want to upgrade to version "|version|"
export FUNKWHALE_VERSION="|version|"
.. code-block:: shell
cd /srv/funkwhale
# hardcode the targeted version your env file
# (look for the FUNKWHALE_VERSION variable)
nano .env
# Load your environment variables
source .env
# Download newest nginx configuration file
curl -L -o nginx/funkwhale.template "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/$FUNKWHALE_VERSION/deploy/docker.nginx.template"
curl -L -o nginx/funkwhale_proxy.conf "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/$FUNKWHALE_VERSION/deploy/docker.funkwhale_proxy.conf"
# Pull the new version containers
docker-compose pull
# Apply the database migrations
docker-compose run --rm api python manage.py migrate
# Relaunch the containers
docker-compose up -d
.. warning::
You may sometimes get the following warning while applying migrations::
"Your models have changes that are not yet reflected in a migration, and so won't be applied."
This is a warning, not an error, and it can be safely ignored.
Never run the ``makemigrations`` command yourself.
Upgrading the Postgres container
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
With some Funkwhale releases, it is recommended to upgrade the version of the
Postgres database server container. For example, Funkwhale 0.17 recommended
Postgres 9.4, but Funkwhale 0.18 recommends Postgres 11. When upgrading
Postgres, it is not sufficient to change the container referenced in
``docker-compose.yml``. New major versions of Postgres cannot read the databases
created by older major versions. The data has to be exported from a running
instance of the old version and imported by the new version.
Thankfully, there is a Docker container available to automate this process. You
can use the following snippet to upgrade your database in ``./postgres``,
keeping a backup of the old version in ``./postgres-old``:
.. code-block:: shell
# Replace "9.4" and "11" with the versions you are migrating between.
export OLD_POSTGRES=9.4
export NEW_POSTGRES=11
docker-compose stop postgres
docker run --rm \
-v $(pwd)/data/postgres:/var/lib/postgresql/${OLD_POSTGRES}/data \
-v $(pwd)/data/postgres-new:/var/lib/postgresql/${NEW_POSTGRES}/data \
tianon/postgres-upgrade:${OLD_POSTGRES}-to-${NEW_POSTGRES}
# Add back the access control rule that doesn't survive the upgrade
echo "host all all all trust" | sudo tee -a ./data/postgres-new/pg_hba.conf
# Swap over to the new database
mv ./data/postgres ./data/postgres-old
mv ./data/postgres-new ./data/postgres
Non-docker setup
----------------
If you installed Funkwhale using the install script, upgrading is done using ``sh -c "$(curl -sSL https://get.funkwhale.audio/upgrade.sh)"``. Make sure to run this command with root permissions.
If you manually installed Funkwhale, please use the following instructions.
Upgrade the static files
^^^^^^^^^^^^^^^^^^^^^^^^
On non-docker setups, the front-end app
is updated separately from the API. This is as simple as downloading
the zip with the static files and extracting it in the correct place.
The following example assume your setup match :ref:`frontend-setup`.
.. parsed-literal::
# this assumes you want to upgrade to version "|version|"
export FUNKWHALE_VERSION="|version|"
cd /srv/funkwhale
sudo -u funkwhale curl -L -o front.zip "https://dev.funkwhale.audio/funkwhale/funkwhale/builds/artifacts/$FUNKWHALE_VERSION/download?job=build_front"
sudo -u funkwhale unzip -o front.zip
sudo -u funkwhale rm front.zip
Upgrading the API
^^^^^^^^^^^^^^^^^
On non-docker, upgrade involves a few more commands. We assume your setup
match what is described in :doc:`/installation/debian`:
.. parsed-literal::
# this assumes you want to upgrade to version "|version|"
export FUNKWHALE_VERSION="|version|"
cd /srv/funkwhale
# download more recent API files
sudo -u funkwhale curl -L -o "api-$FUNKWHALE_VERSION.zip" "https://dev.funkwhale.audio/funkwhale/funkwhale/-/jobs/artifacts/$FUNKWHALE_VERSION/download?job=build_api"
sudo -u funkwhale unzip "api-$FUNKWHALE_VERSION.zip" -d extracted
sudo -u funkwhale rm -rf api/ && sudo -u funkwhale mv extracted/api .
sudo -u funkwhale rm -rf extracted
sudo -u funkwhale rm api-$FUNKWHALE_VERSION.zip
# update os dependencies
sudo api/install_os_dependencies.sh install
cd api
sudo -u funkwhale -H -E poetry install --no-dev
# collect static files
sudo -u funkwhale -H -E poetry run python manage.py collectstatic --no-input
# stop the services
sudo systemctl stop funkwhale.target
# apply database migrations
sudo -u funkwhale -H -E poetry run python api/manage.py migrate
# restart the services
sudo systemctl start funkwhale.target
.. note::
If you see a PermissionError when running the ``migrate`` command, try running the following commands by hand, and relaunch the migrations::
sudo -u postgres psql funkwhale -c 'CREATE EXTENSION IF NOT EXISTS "citext";'
sudo -u postgres psql funkwhale -c 'CREATE EXTENSION IF NOT EXISTS "unaccent";'
.. warning::
You may sometimes get the following warning while applying migrations::
"Your models have changes that are not yet reflected in a migration, and so won't be applied."
This is a warning, not an error, and it can be safely ignored.
Never run the ``makemigrations`` command yourself.
docs/admin/url.rst deleted 100644 → 0
+ 0
− 98
View file @ f0857ae5
Changing Your Instance URL
==========================
.. DANGER::
We highly recommend not to change your instance URL. Members of the community tried to do this and documented their steps here.
This guide might be incomplete or fail for your instance. There is no support for this procedure and likely no way back.
At some point, you may wish to change your instance URL. In order to
do this, you will need to change the following:
- The instance URL in your .env file
- The instance URL in your ``/etc/nginx/sites-enabled/funkwhale.conf`` or ``/etc/apache2/sites-enabled/funkwhale.conf`` depending on your web server setup
- Any references to the old URL in your database
The changes to the database can be achieved with the ``fix_federation_ids`` script in the ``manage.py``
file.
Example output:
.. code-block:: shell
# For Docker setups
docker-compose run --rm api python manage.py fix_federation_ids https://old-url https://new-url --no-dry-run --no-input
# For non-Docker setups
python manage.py fix_federation_ids https://old-url https://new-url --no-dry-run --no-input
# 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…
On Docker Installations
-----------------------
If you have followed the :doc:`Docker installation instructions <../installation/docker>`, you
will need to do the following:
- Edit your .env file to change the ``FUNKWHALE_HOSTNAME`` and ``DJANGO_ALLOWED_HOSTS`` value to your new URL
- Edit your ``/etc/nginx/sites-enabled/funkwhale.conf`` file to change the ``server_name`` values to your new URL
- Run the following command to change all mentions of your old instance URL in the database:
.. code-block:: shell
docker-compose run --rm api python manage.py fix_federation_ids https://old-url https://new-url --no-dry-run --no-input
- Restart Nginx or Apache to pick up the new changes
.. code-block:: shell
# For Nginx
sudo systemctl restart nginx
# For Apache
sudo systemctl restart apache2
On Non-Docker Installations
---------------------------
If you have followed the :doc:`non-docker setup <../installation/debian>`, you will need to do the following:
- Edit your .env file to change the ``FUNKWHALE_HOSTNAME`` and ``DJANGO_ALLOWED_HOSTS`` value to your new URL
- Edit your ``/etc/nginx/sites-enabled/funkwhale.conf`` file to change the ``server_name`` values to your new URL
- Run the following command to change all mentions of your old instance URL in the database:
.. code-block:: shell
python manage.py fix_federation_ids https://old-url https://new-url --no-dry-run --no-input
- Restart Nginx or Apache to pick up the new changes
.. code-block:: shell
# For Nginx
sudo systemctl restart nginx
# For Apache
sudo systemctl restart apache2
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment