@@ -882,8 +882,8 @@ Tags are used in various places to enhance user experience:
- The custom radio builder now supports using tags
- Subsonic apps that support genres - such as DSub or Ultrasonic - should display this information as well
If you are a pod admin and want to extract tags from already uploaded content, you run `this snippet <https://dev.funkwhale.audio/funkwhale/funkwhale/snippets/43>`_
and `this snippet <https://dev.funkwhale.audio/funkwhale/funkwhale/snippets/44>`_ in a ``python manage.py shell``.
If you are a pod admin and want to extract tags from already uploaded content, you run `this snippet <https://dev.funkwhale.audio/funkwhale/funkwhale/snippets/43>`__
and `this snippet <https://dev.funkwhale.audio/funkwhale/funkwhale/snippets/44>`__ in a ``python manage.py shell``.
Content and account reports
^^^^^^^^^^^^^^^^^^^^^^^^^^^
...
...
@@ -899,8 +899,8 @@ Federation of the reports will be supported in a future release.
For more information about this feature, please check out our documentation:
@@ -7,9 +7,7 @@ Funkwhale supports LDAP through the Django LDAP authentication module and by set
.. warning::
Note the following restrictions when using LDAP:
* LDAP-based users cannot change passwords inside the app.
Note that LDAP-based users cannot change their password inside the app.
Dependencies
------------
...
...
@@ -21,23 +19,25 @@ Environment variables
LDAP authentication is configured entirely through the environment variables. The following options enable the LDAP features:
Basic 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``.
- ``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:
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.
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``.
- ``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``.
- On the destination server, use rsync to copy the contents of `/srv/funwkhale/data/media/music` and `/srv/funkwhale/data/music` from the original server
On the origin server, create a database backup:
.. code-block:: shell
rsync -a <your username>@<original server IP/hostname>:/srv/funkwhale/data/media/ /srv/funkwhale/data/media/
rsync -a <your username>@<original server IP/hostname>:/srv/funkwhale/data/music/ /srv/funkwhale/data/music/
- Copy your .env file and database backup from your original server
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
rsync -a <your username>@<original server IP/hostname>:/srv/funkwhale/config/.env /srv/funkwhale/config/
rsync -a <your username>@<original server IP/hostname>:/srv/funkwhale/db.dump /srv/funkwhale/
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/
- Restore the database dump
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 -u funkwhale pg_restore -d funkwhale db.dump
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.
- Once the database has been restored, follow the database migration steps from the guide to complete the installation
- Ensure that all DNS changes have been made and start the services
Ensure that all DNS changes have been made and start the services:
.. code-block:: shell
sudo systemctl start funkwhale.target
Docker
------
- On the target 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 original server, create a database backup
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 destination server, use rsync to copy the contents of `/srv/funwkhale/data/media/music` and `/srv/funkwhale/data/music` from the original server
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
rsync -a <your username>@<original server IP/hostname>:/srv/funkwhale/data/media/ /srv/funkwhale/data/media/
rsync -a <your username>@<original server IP/hostname>:/srv/funkwhale/data/music/ /srv/funkwhale/data/music/
- Copy your .env file and database backup from your original server
origin = <origin server IP/hostname>
username = <your username>
.. code-block:: shell
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 <your username>@<original server IP/hostname>:/srv/funkwhale/.env /srv/funkwhale/
rsync -a <your username>@<original server IP/hostname>:/srv/funkwhale/db.dump /srv/funkwhale/
rsync -a $username@$origin:/srv/funkwhale/.env /srv/funkwhale/
rsync -a $username@$origin:/srv/funkwhale/db.dump /srv/funkwhale/
@@ -13,8 +13,8 @@ of registered policies, in turn. Each policy can mutate the message, leave it as
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>`_)
- 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>`__)
- 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 :ref:`setting-MUSIC_DIRECTORY_PATH`, :ref:`setting-MUSIC_DIRECTORY_SERVE_PATH` and :ref:`setting-REVERSE_PROXY_TYPE` are configured properly, and that the files are readable by the webserver
- 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>``
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.
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 db
^^^^^^^^^^^^^
On docker setups, you have to ``pg_dumpall`` in container ``funkwhale_postgres_1``:
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.
