Commit 2cb71d4a authored by jovuit's avatar jovuit Committed by Georg Krause
Browse files

Restructure and Improve docs

parent 8273feb5
......@@ -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:
- `User documentation <https://docs.funkwhale.audio/moderator/reports.html>`_
- `Moderator documentation <https://docs.funkwhale.audio/users/reports.html>`_
- `User documentation <https://docs.funkwhale.audio/moderator/reports.html>`__
- `Moderator documentation <https://docs.funkwhale.audio/users/reports.html>`__
Account deletion
^^^^^^^^^^^^^^^^
......@@ -913,7 +913,7 @@ to other known servers on the federation.
For more information about this feature, please check out our documentation:
- `User documentation <https://docs.funkwhale.audio/users/account.html>`_
- `User documentation <https://docs.funkwhale.audio/users/account.html>`__
Landing and about page redesign [Manual action suggested]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
......@@ -977,7 +977,7 @@ Both messages will appear for the first time 15 days after signup, in the notifi
Replaced Daphne by Gunicorn/Uvicorn [manual action required, non-docker only]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To improve the performance, stability and reliability of Funkwhale's web processes,
we now recommend using Gunicorn and Uvicorn instead of Daphne. This combination unlock new use cases such as:
......@@ -1295,7 +1295,7 @@ special permissions, such as modifying instance settings or moderation (but this
enabled in a future release).
If you want to start building an app on top of Funkwhale's API, please check-out
`https://docs.funkwhale.audio/api.html`_ and `https://docs.funkwhale.audio/developers/authentication.html`_.
https://docs.funkwhale.audio/api.html and https://docs.funkwhale.audio/developers/authentication.html.
Better error handling and display during import
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
......@@ -1313,7 +1313,7 @@ Storing all media files on the Funkwhale server itself may not be possible or de
in all scenarios. You can now configure Funkwhale to store those files in a S3
bucket instead.
Check-out `https://docs.funkwhale.audio/admin/external-storages.html`_ if you want to use
Check-out https://docs.funkwhale.audio/admin/external-storages.html if you want to use
this feature.
Prune library command
......@@ -1324,7 +1324,7 @@ metadata even if no associated files exist.
To help with that, we now offer a ``prune_library`` management command you can run
to purge your database from obsolete entries. `Please refer to our documentation
for usage instructions <https://docs.funkwhale.audio/admin/commands.html#pruning-library>`_.
for usage instructions <https://docs.funkwhale.audio/admin/commands.html#pruning-library>`__.
Check in-place files command
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
......@@ -1335,7 +1335,7 @@ files in the database, which results in unplayable tracks.
To help with that, we now offer a ``check_inplace_files`` management command you can run
to purge your database from obsolete files. `Please refer to our documentation
for usage instructions <https://docs.funkwhale.audio/admin/commands.html#remove-obsolete-files-from-database>`_.
for usage instructions <https://docs.funkwhale.audio/admin/commands.html#remove-obsolete-files-from-database>`__.
Features:
......@@ -2994,7 +2994,7 @@ Starting from this release, we now offer a dedicated interface directly
in the front-end. You can view and edit all your instance settings from here,
assuming you have the required permissions.
This interface is available at ``/manage/settings` and via link in the sidebar.
This interface is available at ``/manage/settings`` and via link in the sidebar.
Storage of bitrate, size and length in database
......@@ -3626,7 +3626,7 @@ Features:
- Switched to django-channels and daphne for serving HTTP and websocket (#34)
Upgrades notes
**************
^^^^^^^^^^^^^^
This version contains breaking changes in the way funkwhale is deployed,
please read the notes carefully.
......
Added server uninstallation documentation (\!1314)
Fixed broken backup documentation (#1345)
Refactored installation documentation and other small documentation adjustments (\!1314)
......@@ -14,8 +14,8 @@ If you've followed the setup instructions in :doc:`../installation/docker`, here
Multi-container installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Backup the db
^^^^^^^^^^^^^
Backup the database
^^^^^^^^^^^^^^^^^^^
On docker setups, you have to ``pg_dumpall`` in container ``funkwhale_postgres_1``:
......@@ -47,8 +47,8 @@ On docker setups, the configuration file is located at the root level:
Non-docker setup
----------------
Backup the db
^^^^^^^^^^^^^
Backup the database
^^^^^^^^^^^^^^^^^^^
On non-docker setups, you have to ``pg_dump`` as user ``postgres``:
......
......@@ -2,8 +2,9 @@ Instance configuration
======================
General configuration is achieved using two type of settings:
:ref:`environment variables <environment-variables>` and
:ref:`instance settings <instance-settings>`.
- :ref:`environment variables <environment-variables>` and
- :ref:`instance settings <instance-settings>`.
.. _environment-variables:
......@@ -11,8 +12,7 @@ Environment variables
---------------------
Those are located in your ``.env`` file, which you should have created
during installation. A full list of available variables can be seen
:ref:`below <environment-variables>`.
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.
......@@ -20,7 +20,9 @@ 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.
on environment variables::
sudo systemctl restart funkwhale.target
.. note::
......@@ -28,10 +30,11 @@ and technical aspects of your instance, such as database credentials.
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"))``
instance using the following command::
python3 -c 'import urllib.parse; print(urllib.parse.quote_plus("p@ssword"))
cf. https://github.com/joke2k/django-environ#using-unsafe-characters-in-urls
See as well https://github.com/joke2k/django-environ#using-unsafe-characters-in-urls
.. _instance-settings:
......@@ -186,21 +189,20 @@ 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
- 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`
settings as described in :ref:`instance-settings`;
- **Manage library**: users with this permission can import new music in the
instance
instance;
- **Manage library federation**: users with this permission can ask to federate with
other instances, and accept/deny federation requests from other instances
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
......@@ -216,7 +218,7 @@ 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:
......@@ -244,11 +246,11 @@ If you are using nginx, add the following snippet to your vhost configuration::
alias /srv/funkwhale/custom/settings.json;
}
On apache, add the following to your vhost configuration::
On Apache, add the following to your vhost configuration::
Alias /settings.json /srv/funkwhale/custom/settings.json
Then reload your reverse proxy.
Then, reload your reverse proxy.
At this point, visiting ``https://yourinstanceurl/settings.json`` should serve the content
of the settings.json file.
......@@ -285,8 +287,8 @@ 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
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
......@@ -311,7 +313,7 @@ On nginx, add the following snippet to your vhost config::
alias /srv/funkwhale/custom;
}
On apache, use the following::
On Apache, use the following::
Alias /custom /srv/funkwhale/custom
......
......@@ -93,8 +93,8 @@ following behaviour during import:
Because those files are not managed by Funkwhale, we offer additional
configuration options to ensure the webserver can serve them properly:
- :ref:`setting-MUSIC_DIRECTORY_PATH`
- :ref:`setting-MUSIC_DIRECTORY_SERVE_PATH`
- :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
......
......@@ -15,7 +15,11 @@ Setup Guides
configuration
importing-music
external-storages
optimization
backup
migration
uninstall
ldap
Administration
--------------
......@@ -29,10 +33,11 @@ Administration
upgrading
mrf
Troubleshooting Issues
----------------------
Troubleshooting
---------------
.. toctree::
:maxdepth: 2
troubleshooting
debugging
......@@ -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``.
......@@ -6,6 +6,8 @@ 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
------------
......@@ -18,67 +20,83 @@ following:
Non-Docker
----------
- On the target server, run through the :doc:`installation steps<../installation/debian>` but skip the Database setup steps
- Stop all funkwhale related services on the destination server
- On the original server, create a database backup
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 -u funkwhale pg_dump -d funkwhale > "db.dump"
sudo systemctl stop funkwhale.target
- 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/
sudo -u funkwhale pg_dump -d funkwhale > "db.dump"
- 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 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 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/
- Restore the database dump
Restore the database dump:
.. code-block:: shell
docker exec -i funkwhale_postgres_1 pg_restore -c -U postgres -d postgres < "db.dump"
- Once the database has been restored, run the migrations
- Ensure that all DNS changes have been made and start the services
\ No newline at end of file
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.
\ No newline at end of file
......@@ -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>`__)
.. note::
......
......@@ -50,12 +50,12 @@ Diagnostic tools:
Common problems
***************
Instance work properly, but audio files are not served (404 error)
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 :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>``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......
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
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 db
^^^^^^^^^^^^^
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 db
^^^^^^^^^^^^^
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.