Commit 21fb39dd authored by Ciarán Ainsworth's avatar Ciarán Ainsworth Committed by Eliot Berriot

Update docs/developers/index.rst, docs/developers/subsonic.rst files

Deleted developers/index.rst, developers/subsonic.rst files
parent 979eac9d
......@@ -2203,7 +2203,7 @@ On both docker and non-docker setup, you'll also have to update your nginx
configuration for websocket support. Ensure you have the following blocks
included in your virtualhost file:
.. code-block:: txt
.. code-block:: text
map $http_upgrade $connection_upgrade {
default upgrade;
......
......@@ -512,7 +512,7 @@ It's possible to nest multiple component parts to reach a higher level of detail
- ``Content/*/Form.Help text``
Collecting translatable strings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you want to ensure your translatable strings are correctly marked for translation,
you can try to extract them.
......
......@@ -38,7 +38,7 @@ to help you understand the scale of the changes:
+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
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
......
......@@ -14,7 +14,7 @@ and technical aspects of your instance, such as database credentials.
.. 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.
......@@ -38,7 +38,7 @@ settings in this interface.
.. note::
If you have any issue with the web application, a management interface is also
available for those settings from Django's administration interface. It's
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.
......@@ -110,7 +110,7 @@ for this value. For non-docker installation, you can use any absolute path.
Default: :ref:`setting-MUSIC_DIRECTORY_PATH`
When using Docker, the value of :ref:`MUSIC_DIRECTORY_PATH` in your containers
When using Docker, the value of :ref:`setting-MUSIC_DIRECTORY_PATH` in your containers
may differ from the real path on your host. Assuming you have the following directive
in your :file:`docker-compose.yml` file::
......@@ -156,7 +156,7 @@ permissions are:
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 Django's admin at ``/api/admin/`` and grant permissions
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
......
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.
......@@ -28,7 +28,7 @@ Deleting a Track
* 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
......
......@@ -151,4 +151,4 @@ From other instances
--------------------
Funkwhale also supports importing music from other instances. Please refer
to :doc:`federation` for more details.
to :doc:`../federation/index` for more details.
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
Administration
--------------
.. toctree::
:maxdepth: 2
django
url
upgrading
Troubleshooting Issues
----------------------
.. toctree::
:maxdepth: 2
troubleshooting
......@@ -14,7 +14,7 @@ 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 </architecture>` for that.
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:
......@@ -28,54 +28,6 @@ Each category comes with its own set of diagnose tools and/or commands we will d
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.
Frontend issues
^^^^^^^^^^^^^^^
Diagnostic tools:
- Javascript and network logs from your browser console (see instructions on how to open it in `Chrome <https://developers.google.com/web/tools/chrome-devtools/console/>`_ and `Firefox <https://developer.mozilla.org/en-US/docs/Tools/Web_Console/Opening_the_Web_Console>`_
- Proxy and API access and error logs (see :ref:`access-logs`)
- The same operation works from a different browser
Common problems
***************
The front-end is completely blank
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You are visiting Funkwhale, but you don't see anything.
- Try from a different browser
- Check network errors in your browser console. If you see responses with 40X or 50X statuses, there is probably an issue with the webserver configuration
- If you don't see anything wrong in the network console, check the Javascript console
- Disable your browser extensions (like adblockers)
Music is not playing
~~~~~~~~~~~~~~~~~~~~
You have some tracks in your queue that don't play, or the queue is jumping from one track to the next until
there is no more track available:
- Try with other tracks. If it works with some tracks but not other tracks, this may means that the failing tracks are not probably imported
or that your browser does not support a specific audio format
- Check the network and javascript console for potential errors
Tracks are not appending to the queue
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When clicking on "Play", "Play all albums" or "Play all" buttons, some tracks are not appended to the queue. This is
actually a feature of Funkwhale: those tracks have no file associated with them, so we cannot play them.
Specific pages are loading forever or blank
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When viewing a given page, the page load never ends (you continue to see the spinner), or nothing seems to appear at all:
- Ensure your internet connection is up and running
- Ensure your instance is up and running
- Check the network and javascript console for potential errors
Backend issues
^^^^^^^^^^^^^^
......
......@@ -13,7 +13,7 @@ Upgrading your Funkwhale instance to a newer version
Reading the release notes
-------------------------
Please take a few minutes to read the :doc:`changelog`: updates should work
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.
......@@ -33,7 +33,7 @@ when possible.
Docker setup
------------
If you've followed the setup instructions in :doc:`Docker`, upgrade path is
If you've followed the setup instructions in :doc:`../installation/docker`, upgrade path is
easy:
Mono-container installation
......
Changing Your Instance URL
==========================
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 occurences 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
\ No newline at end of file
......@@ -19,6 +19,8 @@
#
import os
import sys
import datetime
from shutil import copyfile
sys.path.insert(0, os.path.abspath("../api"))
......@@ -48,8 +50,9 @@ source_suffix = ".rst"
master_doc = "index"
# General information about the project.
year = datetime.datetime.now().year
project = "funkwhale"
copyright = "2017, Eliot Berriot"
copyright = "{}, Eliot Berriot".format(year)
author = "Eliot Berriot"
# The version info for the project you're documenting, acts as replacement for
......@@ -81,7 +84,6 @@ pygments_style = "sphinx"
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
......@@ -100,7 +102,6 @@ html_theme = "alabaster"
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ["_static"]
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
......@@ -155,3 +156,48 @@ texinfo_documents = [
"Miscellaneous",
)
]
# -- Build legacy redirect files -------------------------------------------
# Define list of redirect files to be build in the Sphinx build process
redirect_files = [
('importing-music.html', 'admin/importing-music.html'),
('architecture.html', 'developer/architecture.html'),
('troubleshooting.html', 'admin/troubleshooting.html'),
('configuration.html', 'admin/configuration.html'),
('upgrading/index.html', '../admin/upgrading.html'),
('upgrading/0.17.html', '../admin/0.17.html'),
('users/django.html', '../admin/django.html'),
]
# Generate redirect template
redirect_template = """\
<html>
<head>
<meta http-equiv="refresh" content="1; url={new}" />
<script>
window.location.href = "{new}"
</script>
</head>
</html>
"""
# Tell Sphinx to copy the files
def copy_legacy_redirects(app, docname):
if app.builder.name == 'html':
for html_src_path, new in redirect_files:
page = redirect_template.format(new=new)
target_path = app.outdir + '/' + html_src_path
if not os.path.exists(os.path.dirname(target_path)):
os.makedirs(os.path.dirname(target_path))
with open(target_path, 'w') as f:
f.write(page)
def setup(app):
app.connect('build-finished', copy_legacy_redirects)
......@@ -50,7 +50,7 @@ or persist data.
Third-party apps
----------------
Since Funkwhale implements a subset of the Subsonic API, it's compatible with existing apps such
Since Funkwhale implements a subset of the Subsonic API, it's compatible with existing :doc:`apps <../users/apps>` such
as DSub, Ultrasonic or Clementine that support this API. Those apps can be used as a replacement
or in conjunction of the web interface, but the underlying data is the same.
......
......@@ -10,6 +10,7 @@ Reference
.. toctree::
:maxdepth: 2
architecture
../api
../federation/index
subsonic
......@@ -57,7 +57,6 @@ in our payload, which you can use to adapt your client behaviour if needed:
{
"subsonic-response": {
...
"type": "funkwhale",
"funkwhaleVersion": "0.17"
}
......
......@@ -24,7 +24,7 @@ Funkwhale is not bundled with any music, and you'll have to import your own musi
At the moment, you can feed your existing music library to the server either by uploading it or by using :ref:`in-place-import` from a server-side directory. Assuming the files have the correct tags defined, they will be imported seamlessly.
You can also access music being made available by other Funkwhale instances using :doc:`federation`.
You can also access music being made available by other Funkwhale instances using :doc:`/federation/index`.
Metadata
---------
......
......@@ -317,7 +317,7 @@ Supported on
- :ref:`object-Library` objects
Example (on :ref:`object-Library`)
************************
**********************************
.. code-block:: json
......@@ -339,7 +339,7 @@ Example (on :ref:`object-Library`)
}
Example (on :ref:`object-audio`)
**********************
********************************
.. code-block:: json
......
......@@ -11,14 +11,10 @@ Funkwhale is a self-hosted, modern free and open-source music server, heavily in
.. toctree::
:maxdepth: 2
users/index
features
architecture
installation/index
upgrading/index
configuration
troubleshooting
importing-music
users/index
moderator/index
admin/index
developers/index
third-party
contributing
......
......@@ -207,6 +207,7 @@ You can then edit the file: the file is heavily commented, and the most relevant
configuration options are mentioned at the top of the file.
.. code-block:: shell
nano /srv/funkwhale/api/.env
Paste the secret key you generated earlier at the entry
......
......@@ -196,4 +196,4 @@ Now, you just need to configure your :ref:`reverse-proxy <reverse-proxy-setup>`.
About music acquisition
-----------------------
If you want to :doc:`import music located on the server </importing-music>`, you can put it in the ``data/music`` directory and it will become readable by the importer.
If you want to :doc:`import music located on the server <../admin/importing-music>`, you can put it in the ``data/music`` directory and it will become readable by the importer.
......@@ -93,6 +93,6 @@ On Arch Linux and its derivatives:
This should be enough to have your redis server set up.
External Authentication (LDAP)
----------------------
------------------------------
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. See :doc:`./ldap` for more details.
......@@ -204,6 +204,7 @@ On non-docker deployments, run the following commands:
Finally, enable the resulting configuration:
.. code-block:: bash
ln -s /etc/nginx/sites-available/funkwhale.conf /etc/nginx/sites-enabled/
.. warning::
......@@ -212,8 +213,8 @@ Finally, enable the resulting configuration:
in the ``_protected/music`` location matches your MUSIC_DIRECTORY_SERVE_PATH
env var.
HTTS Configuration
::::::::::::::::::
HTTPS Configuration
:::::::::::::::::::
At this point you will need a SSL certificate to enable HTTPS on your server.
The default nginx configuration assumes you have those available at ``/etc/letsencrypt/live/${FUNKWHALE_HOSTNAME}/``, which
......@@ -274,7 +275,7 @@ Check the configuration is valid with ``apache2ctl configtest``, and once you're
done, load the new configuration with ``service apache2 restart``.
About internal locations
~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^
Music (and other static) files are never served by the app itself, but by the reverse
proxy. This is needed because a webserver is way more efficient at serving
......
......@@ -42,7 +42,7 @@ guide.
Building the mono-container Docker image (funkwhale/funkwhale)
-------------------------------------------------------------
--------------------------------------------------------------
This image is intended to be used in conjunction with our :ref:`Mono-container installation guide <docker-mono-container>`.
guide.
......
Moderating Domains
==================
Moderation rules can be used to control how your instance interacts with other domains.
They can be useful for keeping unwanted material and users out of your instance.
Managing Domains
----------------
Add a Domain
^^^^^^^^^^^^
Adding a domain allows you to create rules pre-emptively and proactively moderate content on your
instance. Domains with which users have already interacted will appear in the domains list.
To add a new domain:
- Navigate to the "Moderation" menu under "Administration"
- Select "Domains" along the top
- In the top right, enter the URL of the domain you want to federate with in the "Add a domain" box and click "Add"
- You will then be taken to an overview page showing details about the instance
Purge Domain Data
^^^^^^^^^^^^^^^^^
.. warning::
Purging domain data will remove all tracks, libraries, and caches associated with
the domain. This can have severe knock-on effects for users who have any of these
in their favorites, playlists, or followed libraries. Be careful when performing
this action.
Purging data from a domain can be useful if a domain is uploading offensive or illegal
media you do not want served on your instance.
- Navigate to the "Moderation" menu under "Administration"
- Select "Domains" along the top
- Find the domain whose data you wish to purge and select the checkbox next to it
- Select "Purge" from the "Actions" drop-down menu and click on "Go"
- A pop up will appear warning you of the consequences. If you want to continue with the purge, click "Launch"
Moderation Rules
----------------
Add a Moderation Rule to a Domain
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Moderation rules can be useful for managing interaction with domains.
To add a moderation rule:
- Navigate to the "Moderation" menu under "Administration"
- Select "Domains" along the top
- Find the domain you wish to add a rule to and click on it
- In the top right, select "Add a moderation policy"
- Give a reason for your rule creation in the "Reason" box. This can help other moderators understand the action
- To block all interaction with the domain **and purge all content**, select "Block Everything"
- To only block media elements such as audio, avatars, and album art, select "Reject Media"
- When you have finished creating your rule, click "Create" to save the rule
Edit a Moderation Rule
^^^^^^^^^^^^^^^^^^^^^^
Sometimes a previously created moderation rule needs to be updated to lessen or increase
its severity.
To update an existing moderation rule:
- Navigate to the "Moderation" menu under "Administration"
- Select "Domains" along the top
- Find the domain whose rule you wish to edit and click on it
- In the top right, select "Update" under your existing rule
- Update the reason for your rule creation in the "Reason" box. This can help other moderators understand the action
- To block all interaction with the domain **and purge all content**, select "Block Everything"
- To only block media elements such as audio, avatars, and album art, select "Reject Media"
- When you have finished editing your rule, click "Create" to save the rule
Remove a Moderation Rule From a Domain
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If a domain is no longer subject to moderation, you can remove existing rules to enable
full federation with the instance again.
To remove a moderation rule from a domain:
- Navigate to the "Moderation" menu under "Administration"
- Select "Domains" along the top
- Find the domain you wish to remove a rule from and click on it
- In the top right, select "Update" under your existing rule
- Click on "Delete"
- A pop up will appear warning that the action is irreversible. If you want to continue, select "Delete moderation rule"
Moderator Documentation
=========================
This documentation is targeted at instance moderators. Moderators have enhanced permissions
which allow them to moderate federated accounts and domains.
Moderation Guides
-----------------
.. toctree::
:maxdepth: 2
domains
users
\ No newline at end of file
Moderating Users
==================
Moderation rules can be used to control how your instance interacts with accounts on other domains.
They can be useful for keeping unwanted material and users out of your instance.
Managing Accounts
-----------------
Purge Account Data
^^^^^^^^^^^^^^^^^^
.. warning::
Purging account data will remove all tracks, libraries, and caches associated with
the account. This can have severe knock-on effects for users who have any of these
in their favorites, playlists, or followed libraries. Be careful when performing
this action.
Purging data from an account can be useful if the account is uploading offensive or illegal
media you do not want served on your instance.
- Navigate to the "Moderation" menu under "Administration"
- Select "Accounts" along the top
- Find the account whose data you wish to purge and select the checkbox next to it
- Select "Purge" from the "Actions" drop-down menu and click on "Go"
- A pop up will appear warning you of the consequences. If you want to continue with the purge, click "Launch"
Moderation Rules
----------------
Add a Moderation Rule to an Account
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. note::
Moderation rules only apply to accounts on other instances
Moderation rules can be useful for managing interaction with Accounts.
To add a moderation rule:
- Navigate to the "Moderation" menu under "Administration"
- Select "Accounts" along the top
- Find the Account you wish to add a rule to and click on it
- In the top right, select "Add a moderation policy"
- Give a reason for your rule creation in the "Reason" box. This can help other moderators understand the action
- To block all interaction with the account **and purge all content**, select "Block Everything"
- To only block media elements such as audio, avatars, and album art, select "Reject Media"
- When you have finished creating your rule, click "Create" to save the rule
Edit a Moderation Rule
^^^^^^^^^^^^^^^^^^^^^^
Sometimes a previously created moderation rule needs to be updated to lessen or increase
its severity.
To update an existing moderation rule:
- Navigate to the "Moderation" menu under "Administration"
- Select "Accounts" along the top
- Find the account whose rule you wish to edit
- In the top right, select "Update" under your existing rule
- Update the reason for your rule creation in the "Reason" box. This can help other moderators understand the action
- To block all interaction with the account **and purge all content**, select "Block Everything"
- To only block media elements such as audio, avatars, and album art, select "Reject Media"
- When you have finished editing your rule, click "Create" to save the rule
Remove a Moderation Rule From an Account
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If an account is no longer subject to moderation, you can remove existing rules to enable
full federation with the instance again.
To remove a moderation rule from an Account:
- Navigate to the "Moderation" menu under "Administration"
- Select "Accounts" along the top
- Find the account you wish to remove a rule from and click on it
- In the top right, select "Update" under your existing rule
- Click on "Delete"
- A pop up will appear warning that the action is irreversible. If you want to continue, select "Delete moderation rule"
......@@ -49,6 +49,12 @@ Those features as missing:
Enabling Subsonic on your Funkwhale account
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. note::
Accessing Funkwhale from third party apps requires the instance administrator
to enable the Subsonic API setting. If you are unable to use Subsonic, please
contact your administrator.
To log-in on your Funkwhale account from Subsonic clients, you will need to
set a separate Subsonic API password by visiting your settings page.
......
Creating a Funkwhale Account
============================
Before you can start using Funkwhale, you will need to set up an account on an instance. While
some instances allow you to listen to public music anonymously, you will need to create account
to benefit from the full Funkwhale experience.
A list of instances along with other useful information such as version and enabled features can be found
`here <https://network.funkwhale.audio/dashboards/d/overview/network-overview>`_. Servers marked with
"Open registrations" are available to sign up to.
Signing up to an Instance
-------------------------
Once you have chosen the instance you would like to sign up to, creating an account is easy.
1. Click on the "Create an account" option on the left-hand side
2. Enter your preferred username, email address, and password
3. [Optional] enter an Invitation code if you received an invite from an existing user
4. Click on "Create my Account"
5. Once you have created your account, you will be required to log in.
Now that you've created your account, you can go ahead and :doc:`start uploading content to your library <upload>`.
Managing Favorites
==================
Like any media player, Funkwhale allows you to favorite tracks to keep tabs on
the tracks you've enjoyed
Adding Favorites
----------------
From a Library
^^^^^^^^^^^^^^
To add a track to your favorites from your library:
- Search for the song or navigate to its album page
- Click on the gray heart icon next to the track
- Once the gray heart has turned pink, the song will be in your favorites list
From Currently Playing
^^^^^^^^^^^^^^^^^^^^^^