Skip to content
GitLab
Commit 2cb71d4a authored by jovuit's avatar jovuit Committed by Georg Krause
Browse files

Restructure and Improve docs

parent 8273feb5
Hide whitespace changes
Inline Side-by-side
CHANGELOG
View file @ 2cb71d4a
...@@ -882,8 +882,8 @@ Tags are used in various places to enhance user experience: ...@@ -882,8 +882,8 @@ Tags are used in various places to enhance user experience:
- The custom radio builder now supports using tags - The custom radio builder now supports using tags
- Subsonic apps that support genres - such as DSub or Ultrasonic - should display this information as well - 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>`_ 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``. and `this snippet <https://dev.funkwhale.audio/funkwhale/funkwhale/snippets/44>`__ in a ``python manage.py shell``.
Content and account reports Content and account reports
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^
...@@ -899,8 +899,8 @@ Federation of the reports will be supported in a future release. ...@@ -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: For more information about this feature, please check out our documentation:
- `User documentation <https://docs.funkwhale.audio/moderator/reports.html>`_ - `User documentation <https://docs.funkwhale.audio/moderator/reports.html>`__
- `Moderator documentation <https://docs.funkwhale.audio/users/reports.html>`_ - `Moderator documentation <https://docs.funkwhale.audio/users/reports.html>`__
Account deletion Account deletion
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
...@@ -913,7 +913,7 @@ to other known servers on the federation. ...@@ -913,7 +913,7 @@ to other known servers on the federation.
For more information about this feature, please check out our documentation: 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] 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 ...@@ -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] Replaced Daphne by Gunicorn/Uvicorn [manual action required, non-docker only]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To improve the performance, stability and reliability of Funkwhale's web processes, 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: 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 ...@@ -1295,7 +1295,7 @@ special permissions, such as modifying instance settings or moderation (but this
enabled in a future release). enabled in a future release).
If you want to start building an app on top of Funkwhale's API, please check-out 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 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 ...@@ -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 in all scenarios. You can now configure Funkwhale to store those files in a S3
bucket instead. 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. this feature.
Prune library command Prune library command
...@@ -1324,7 +1324,7 @@ metadata even if no associated files exist. ...@@ -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 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 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 Check in-place files command
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
...@@ -1335,7 +1335,7 @@ files in the database, which results in unplayable tracks. ...@@ -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 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 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: Features:
...@@ -2994,7 +2994,7 @@ Starting from this release, we now offer a dedicated interface directly ...@@ -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, in the front-end. You can view and edit all your instance settings from here,
assuming you have the required permissions. 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 Storage of bitrate, size and length in database
...@@ -3626,7 +3626,7 @@ Features: ...@@ -3626,7 +3626,7 @@ Features:
- Switched to django-channels and daphne for serving HTTP and websocket (#34) - Switched to django-channels and daphne for serving HTTP and websocket (#34)
Upgrades notes Upgrades notes
************** ^^^^^^^^^^^^^^
This version contains breaking changes in the way funkwhale is deployed, This version contains breaking changes in the way funkwhale is deployed,
please read the notes carefully. please read the notes carefully.
......
changes/changelog.d/1314.doc 0 → 100644
View file @ 2cb71d4a
Added server uninstallation documentation (\!1314)
changes/changelog.d/1345.doc 0 → 100644
View file @ 2cb71d4a
Fixed broken backup documentation (#1345)
changes/changelog.d/refactored.doc 0 → 100644
View file @ 2cb71d4a
Refactored installation documentation and other small documentation adjustments (\!1314)
docs/admin/backup.rst
View file @ 2cb71d4a
...@@ -14,8 +14,8 @@ If you've followed the setup instructions in :doc:`../installation/docker`, here ...@@ -14,8 +14,8 @@ If you've followed the setup instructions in :doc:`../installation/docker`, here
Multi-container installation Multi-container installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Backup the db Backup the database
^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
On docker setups, you have to ``pg_dumpall`` in container ``funkwhale_postgres_1``: 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: ...@@ -47,8 +47,8 @@ On docker setups, the configuration file is located at the root level:
Non-docker setup Non-docker setup
---------------- ----------------
Backup the db Backup the database
^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
On non-docker setups, you have to ``pg_dump`` as user ``postgres``: On non-docker setups, you have to ``pg_dump`` as user ``postgres``:
......
docs/admin/configuration.rst
View file @ 2cb71d4a
...@@ -2,8 +2,9 @@ Instance configuration ...@@ -2,8 +2,9 @@ Instance configuration
====================== ======================
General configuration is achieved using two type of settings: 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: .. _environment-variables:
...@@ -11,8 +12,7 @@ Environment variables ...@@ -11,8 +12,7 @@ Environment variables
--------------------- ---------------------
Those are located in your ``.env`` file, which you should have created Those are located in your ``.env`` file, which you should have created
during installation. A full list of available variables can be seen during installation. A full list of available variables is given :ref:`below <environment-variables>`.
:ref:`below <environment-variables>`.
Options from this file are heavily commented, and usually target lower level Options from this file are heavily commented, and usually target lower level
and technical aspects of your instance, such as database credentials. and technical aspects of your instance, such as database credentials.
...@@ -20,7 +20,9 @@ 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:: .. note::
You should restart all Funkwhale processes when you change the values You should restart all Funkwhale processes when you change the values
on environment variables. on environment variables::
sudo systemctl restart funkwhale.target
.. note:: .. note::
...@@ -28,10 +30,11 @@ and technical aspects of your instance, such as database credentials. ...@@ -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, Some characters are unsafe to use in configuration variables that are URLs,
such as the user and password in the database and SMTP sections. such as the user and password in the database and SMTP sections.
If those variables contain such characters, they must be urlencoded, for If those variables contain such characters, they must be urlencoded, for
instance using the following command: instance using the following command::
``python3 -c 'import urllib.parse; print(urllib.parse.quote_plus("p@ssword"))``
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: .. _instance-settings:
...@@ -186,21 +189,20 @@ User permissions ...@@ -186,21 +189,20 @@ User permissions
Funkwhale's permission model works as follows: Funkwhale's permission model works as follows:
- Anonymous users cannot do anything unless configured specifically - Anonymous users cannot do anything unless configured specifically;
- Logged-in users can use the application, but cannot do things that affect - Logged-in users can use the application, but cannot do things that affect the whole instance;
the whole instance - Superusers can do anything.
- Superusers can do anything
To make things more granular and allow some delegation of responsibility, To make things more granular and allow some delegation of responsibility,
superusers can grant specific permissions to specific users. Available superusers can grant specific permissions to specific users. Available
permissions are: permissions are:
- **Manage instance-level settings**: users with this permission can edit instance - **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 - **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 - **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 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 can login on the :doc:`Django's admin <django>` at ``/api/admin/`` and grant permissions
...@@ -216,7 +218,7 @@ on ``https://yourinstanceurl/settings.json``. ...@@ -216,7 +218,7 @@ on ``https://yourinstanceurl/settings.json``.
On typical deployments, this url returns a 404 error, which is simply ignored. On typical deployments, this url returns a 404 error, which is simply ignored.
Set-up Set-up
------ ^^^^^^
First, create the settings file: First, create the settings file:
...@@ -244,11 +246,11 @@ If you are using nginx, add the following snippet to your vhost configuration:: ...@@ -244,11 +246,11 @@ If you are using nginx, add the following snippet to your vhost configuration::
alias /srv/funkwhale/custom/settings.json; 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 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 At this point, visiting ``https://yourinstanceurl/settings.json`` should serve the content
of the settings.json file. of the settings.json file.
...@@ -285,8 +287,8 @@ Theming ...@@ -285,8 +287,8 @@ Theming
To theme your Funkwhale instance, you need: To theme your Funkwhale instance, you need:
1. A CSS file for your theme, that can be loaded by the front-end 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 2. To update the value of ``additionalStylesheets`` in your settings.json file to point to your CSS file URL.
.. code-block:: shell .. code-block:: shell
...@@ -311,7 +313,7 @@ On nginx, add the following snippet to your vhost config:: ...@@ -311,7 +313,7 @@ On nginx, add the following snippet to your vhost config::
alias /srv/funkwhale/custom; alias /srv/funkwhale/custom;
} }
On apache, use the following:: On Apache, use the following::
Alias /custom /srv/funkwhale/custom Alias /custom /srv/funkwhale/custom
......
docs/admin/importing-music.rst
View file @ 2cb71d4a
...@@ -93,8 +93,8 @@ following behaviour during import: ...@@ -93,8 +93,8 @@ following behaviour during import:
Because those files are not managed by Funkwhale, we offer additional Because those files are not managed by Funkwhale, we offer additional
configuration options to ensure the webserver can serve them properly: configuration options to ensure the webserver can serve them properly:
- :ref:`setting-MUSIC_DIRECTORY_PATH` - :data:`MUSIC_DIRECTORY_PATH <config.settings.common.MUSIC_DIRECTORY_PATH>`
- :ref:`setting-MUSIC_DIRECTORY_SERVE_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`` 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 and run the `import_files` command from that directory. This will make it possible
......
docs/admin/index.rst
View file @ 2cb71d4a
...@@ -15,7 +15,11 @@ Setup Guides ...@@ -15,7 +15,11 @@ Setup Guides
configuration configuration
importing-music importing-music
external-storages external-storages
optimization
backup
migration migration
uninstall
ldap
Administration Administration
-------------- --------------
...@@ -29,10 +33,11 @@ Administration ...@@ -29,10 +33,11 @@ Administration
upgrading upgrading
mrf mrf
Troubleshooting Issues Troubleshooting
---------------------- ---------------
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
troubleshooting troubleshooting
debugging
docs/installation/ldap.rst → docs/admin/ldap.rst
View file @ 2cb71d4a
...@@ -7,9 +7,7 @@ Funkwhale supports LDAP through the Django LDAP authentication module and by set ...@@ -7,9 +7,7 @@ Funkwhale supports LDAP through the Django LDAP authentication module and by set
.. warning:: .. warning::
Note the following restrictions when using LDAP: Note that LDAP-based users cannot change their password inside the app.
* LDAP-based users cannot change passwords inside the app.
Dependencies Dependencies
------------ ------------
...@@ -21,23 +19,25 @@ Environment variables ...@@ -21,23 +19,25 @@ Environment variables
LDAP authentication is configured entirely through the environment variables. The following options enable the LDAP features: 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_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_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_DN``: LDAP user DN to bind as to perform searches.
* ``LDAP_BIND_PASSWORD``: LDAP user password for bind DN. - ``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_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_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_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``. - ``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``. - ``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_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_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_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_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
View file @ 2cb71d4a
...@@ -6,6 +6,8 @@ existing Funkwhale setup to a new server. This can be helpful ...@@ -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 if you need to boost resources or if you wish to use a different
hosting platform. hosting platform.
In this guide, the existing Funkwhale setup is called the origin server, and the new setup the destination server.
Requirements Requirements
------------ ------------
...@@ -18,67 +20,83 @@ following: ...@@ -18,67 +20,83 @@ following:
Non-Docker Non-Docker
---------- ----------
- On the target server, run through the :doc:`installation steps<../installation/debian>` but skip the Database setup steps On the destination server, run through the :doc:`installation steps<../installation/debian>` with the exception of the following points:
- Stop all funkwhale related services on the destination server
- On the original server, create a database backup - 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 .. 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 .. code-block:: shell
rsync -a <your username>@<original server IP/hostname>:/srv/funkwhale/data/media/ /srv/funkwhale/data/media/ sudo -u funkwhale pg_dump -d funkwhale > "db.dump"
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 .. code-block:: shell
rsync -a <your username>@<original server IP/hostname>:/srv/funkwhale/config/.env /srv/funkwhale/config/ origin = <origin server IP/hostname>
rsync -a <your username>@<original server IP/hostname>:/srv/funkwhale/db.dump /srv/funkwhale/ 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 .. 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 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 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 original server, create a database backup Stop all funkwhale related containers on the destination server.
On the origin server, create a database backup:
.. code-block:: shell .. code-block:: shell
docker exec -t funkwhale_postgres_1 pg_dumpall -c -U postgres > "db.dump" 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 .. code-block:: shell
rsync -a <your username>@<original server IP/hostname>:/srv/funkwhale/data/media/ /srv/funkwhale/data/media/ origin = <origin server IP/hostname>
rsync -a <your username>@<original server IP/hostname>:/srv/funkwhale/data/music/ /srv/funkwhale/data/music/ username = <your username>
- Copy your .env file and database backup from your original server
.. 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 $username@$origin:/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/db.dump /srv/funkwhale/
- Restore the database dump Restore the database dump:
.. code-block:: shell .. code-block:: shell
docker exec -i funkwhale_postgres_1 pg_restore -c -U postgres -d postgres < "db.dump" docker exec -i funkwhale_postgres_1 pg_restore -c -U postgres -d postgres < "db.dump"
- Once the database has been restored, run the migrations 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 Ensure that all DNS changes have been made and start the services.
\ No newline at end of file
docs/admin/mrf.rst
View file @ 2cb71d4a
...@@ -13,8 +13,8 @@ of registered policies, in turn. Each policy can mutate the message, leave it as ...@@ -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: 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>`_) - 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>`_) - 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:: .. note::
......
docs/admin/troubleshooting.rst
View file @ 2cb71d4a
...@@ -50,12 +50,12 @@ Diagnostic tools: ...@@ -50,12 +50,12 @@ Diagnostic tools:
Common problems 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 - 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) - 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>`` Weakref error when running ``python manage.py <command>``