Skip to content
Snippets Groups Projects
Commit 6a20f48a authored by Georg Krause's avatar Georg Krause
Browse files

Merge branch 'install_doc' into 'develop'

Restructure/improve docs

Closes #1345

See merge request !1314
parents 8273feb5 2cb71d4a
No related branches found
No related tags found
No related merge requests found
......@@ -3,15 +3,30 @@ Debian and Arch Linux installation
.. note::
This guide targets Debian 9 (Stretch), which is the latest Debian, as well as Arch Linux.
This guide targets Debian 10 (Buster), which is the latest version available, as well as Arch Linux.
External dependencies
---------------------
Cache setup (Redis)
-------------------
The guides will focus on installing Funkwhale-specific components and
dependencies. However, Funkwhale requires a
:doc:`few external dependencies <./external_dependencies>` for which
documentation is outside of this document scope.
Funkwhale requires a cache server:
- to make the whole system faster, by caching network requests or database queries;
- to handle asynchronous tasks such as music import.
On Debian-like distributions, a redis package is available, and you can
install it:
.. code-block:: shell
sudo apt-get install redis-server
On Arch Linux and its derivatives:
.. code-block:: shell
sudo pacman -S redis
This should be enough to have your redis server set up.
Install system dependencies
---------------------------
......@@ -21,8 +36,9 @@ On Debian-like systems, you can install them using:
.. code-block:: shell
sudo apt-get update
# Install dependencies
# Install system dependencies
sudo apt-get install curl python3-pip python3-venv git unzip libldap2-dev libsasl2-dev gettext-base zlib1g-dev libffi-dev libssl-dev
# Funkwhale dependencies
sudo apt install build-essential ffmpeg libjpeg-dev libmagic-dev libpq-dev postgresql-client python3-dev make
......@@ -30,13 +46,19 @@ On Arch Linux and its derivatives:
.. code-block:: shell
# Install dependencies
# Install system dependencies
sudo pacman -S curl python-pip python-virtualenv git unzip
# Funkwhale dependencies
sudo pacman -S curl file ffmpeg libjpeg-turbo libpqxx python libldap libsasl
Layout
-------
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:`../admin/ldap` for more details.
Installation structure
----------------------
All Funkwhale-related files will be located under ``/srv/funkwhale`` apart
from database files and a few configuration files. We will also have a
......@@ -77,24 +99,23 @@ Create the aforementioned directories:
The ``virtualenv`` directory is a bit special and will be created separately.
Download latest Funkwhale release
----------------------------------
Download the latest Funkwhale release
-------------------------------------
Funkwhale is splitted in two components:
1. The API, which will handle music storage and user accounts
2. The frontend, that will simply connect to the API to interact with its data
1. The API, which will handle music storage and user accounts;
2. The frontend, that will simply connect to the API to interact with its data.
Those components are packaged in subsequent releases, such as 0.1, 0.2, etc.
You can browse the :doc:`changelog </changelog>` for a list of available releases
and pick the one you want to install, usually the latest one should be okay.
In this guide, we'll assume you want to install the latest version of Funkwhale,
which is |version|:
In this guide, we will assume you want to install the latest version of Funkwhale, which is |version|:
First, we'll download the latest api release.
First, we will download the latest api release:
.. parsed-literal::
.. code-block:: shell
curl -L -o "api-|version|.zip" "https://dev.funkwhale.audio/funkwhale/funkwhale/-/jobs/artifacts/|version|/download?job=build_api"
unzip "api-|version|.zip" -d extracted
......@@ -102,9 +123,9 @@ First, we'll download the latest api release.
rm -rf extracted
Then we'll download the frontend files:
Then we will download the frontend files:
.. parsed-literal::
.. code-block:: shell
curl -L -o "front-|version|.zip" "https://dev.funkwhale.audio/funkwhale/funkwhale/-/jobs/artifacts/|version|/download?job=build_front"
unzip "front-|version|.zip" -d extracted
......@@ -114,7 +135,7 @@ Then we'll download the frontend files:
.. note::
You can also choose to get the code directly from the git repo. In this
case, run
case, run::
cd /srv
......@@ -124,7 +145,7 @@ Then we'll download the frontend files:
The above clone command uses the master branch instead of the default develop branch, as master is stable and more suited for production setups.
You'll also need to re-create the folders we make earlier:
You'll also need to re-create the folders we make earlier::
mkdir -p config data/static data/media data/music front
......@@ -158,9 +179,7 @@ This will result in a ``virtualenv`` directory being created in
``/srv/funkwhale/virtualenv``.
In the rest of this guide, we'll need to activate this environment to ensure
dependencies are installed within it, and not directly on your host system.
This is done with the following command:
dependencies are installed within it, and not directly on your host system. This is done with the following command:
.. code-block:: shell
......@@ -195,7 +214,7 @@ Download the sample environment file:
.. note::
if you used git to get the latest version of the code earlier, you can instead do
if you used git to get the latest version of the code earlier, you can instead do::
cp /srv/funkwhale/deploy/env.prod.sample /srv/funkwhale/config/.env
......@@ -215,13 +234,68 @@ configuration options are mentioned at the top of the file.
Paste the secret key you generated earlier at the entry
``DJANGO_SECRET_KEY`` and populate the ``DATABASE_URL``
and ``CACHE_URL`` values based on how you configured
your PostgreSQL and Redis servers in
:doc:`external dependencies <./external_dependencies>`.
your PostgreSQL and Redis servers in.
Database setup
---------------
--------------
You should now be able to import the initial database structure:
Funkwhale requires a PostgreSQL database to work properly. Please refer
to the `PostgreSQL documentation <https://www.postgresql.org/download/>`_
for installation instructions specific to your os.
On Debian-like systems, you would install the database server like this:
.. code-block:: shell
sudo apt-get install postgresql postgresql-contrib
On Arch Linux and its derivatives:
.. code-block:: shell
sudo pacman -S postgresql
On Arch Linux, you'll also need to initialize the database. See `the Arch Linux wiki <https://wiki.archlinux.org/index.php/Postgresql#Initial_configuration>`_.
The remaining steps are heavily inspired from `this Digital Ocean guide <https://www.digitalocean.com/community/tutorials/how-to-set-up-django-with-postgres-nginx-and-gunicorn-on-ubuntu-16-04>`_.
Open a database shell:
.. code-block:: shell
sudo -u postgres psql
Create the project database and user:
.. code-block:: shell
CREATE DATABASE funkwhale WITH ENCODING 'utf8';
CREATE USER funkwhale;
GRANT ALL PRIVILEGES ON DATABASE funkwhale TO funkwhale;
.. warning::
It's important that you use utf-8 encoding for your database,
otherwise you'll end up with errors and crashes later on when dealing
with music metadata that contains non-ascii chars.
Assuming you already have :ref:`created your funkwhale user <create-funkwhale-user>`,
you should now be able to open a postgresql shell:
.. code-block:: shell
sudo -u funkwhale -H psql
Unless you give a superuser access to the database user, you should also
enable some extensions on your database server, as those are required
for Funkwhale to work properly:
.. code-block:: shell
sudo -u postgres psql funkwhale -c 'CREATE EXTENSION "unaccent";'
sudo -u postgres psql funkwhale -c 'CREATE EXTENSION "citext";'
Now that the database has been created, import the initial database structure using the virtualenv created before:
.. code-block:: shell
......@@ -246,7 +320,7 @@ This will create the required tables and rows.
Create an admin account
-----------------------
You can then create your first user account:
Using the virtualenv created before, create your first user account:
.. code-block:: shell
......@@ -274,9 +348,59 @@ in your ``.env`` file.
Systemd unit file
------------------
See :doc:`./systemd`.
.. note::
All the command lines below should be executed as root.
Systemd offers a convenient way to manage your Funkwhale instance if you're
not using docker. We'll see how to setup systemd to properly start a Funkwhale instance.
First, download the sample unitfiles:
.. parsed-literal::
sudo curl -L -o "/etc/systemd/system/funkwhale.target" "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/funkwhale.target"
sudo curl -L -o "/etc/systemd/system/funkwhale-server.service" "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/funkwhale-server.service"
sudo curl -L -o "/etc/systemd/system/funkwhale-worker.service" "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/funkwhale-worker.service"
sudo curl -L -o "/etc/systemd/system/funkwhale-beat.service" "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/funkwhale-beat.service"
This will download three unitfiles:
- ``funkwhale-server.service`` to launch the Funkwhale web server;
- ``funkwhale-worker.service`` to launch the Funkwhale task worker;
- ``funkwhale-beat.service`` to launch the Funkwhale task beat (this is for recurring tasks);
- ``funkwhale.target`` to easily stop and start all of the services at once.
You can of course review and edit them to suit your deployment scenario
if needed, but the defaults should be fine.
Once the files are downloaded, reload systemd:
.. code-block:: shell
sudo systemctl daemon-reload
And start the services:
.. code-block:: shell
sudo systemctl start funkwhale.target
To ensure all Funkwhale processes are started automatically after a reboot, run:
.. code-block:: shell
sudo systemctl enable funkwhale-server
sudo systemctl enable funkwhale-worker
sudo systemctl enable funkwhale-beat
You can check the statuses of all processes like this:
.. code-block:: shell
sudo systemctl status funkwhale-\*
Reverse proxy setup
--------------------
See :ref:`reverse-proxy <reverse-proxy-setup>`.
See :ref:`Reverse proxy <reverse-proxy-setup>`.
External dependencies
=====================
.. note::
Those dependencies are handled automatically if you are
:doc:`deploying using docker <./docker>`
Database setup (PostgreSQL)
---------------------------
Funkwhale requires a PostgreSQL database to work properly. Please refer
to the `PostgreSQL documentation <https://www.postgresql.org/download/>`_
for installation instructions specific to your os.
On Debian-like systems, you would install the database server like this:
.. code-block:: shell
sudo apt-get install postgresql postgresql-contrib
On Arch Linux and its derivatives:
.. code-block:: shell
sudo pacman -S postgresql
On Arch, you'll also need to initialize the database. See `the Arch Linux wiki <https://wiki.archlinux.org/index.php/Postgresql#Initial_configuration>`_.
The remaining steps are heavily inspired from `this Digital Ocean guide <https://www.digitalocean.com/community/tutorials/how-to-set-up-django-with-postgres-nginx-and-gunicorn-on-ubuntu-16-04>`_.
Open a database shell:
.. code-block:: shell
sudo -u postgres psql
Create the project database and user:
.. code-block:: shell
CREATE DATABASE "funkwhale"
WITH ENCODING 'utf8';
CREATE USER funkwhale;
GRANT ALL PRIVILEGES ON DATABASE funkwhale TO funkwhale;
.. warning::
It's important that you use utf-8 encoding for your database,
otherwise you'll end up with errors and crashes later on when dealing
with music metadata that contains non-ascii chars.
Assuming you already have :ref:`created your funkwhale user <create-funkwhale-user>`,
you should now be able to open a postgresql shell:
.. code-block:: shell
sudo -u funkwhale -H psql
Unless you give a superuser access to the database user, you should also
enable some extensions on your database server, as those are required
for Funkwhale to work properly:
.. code-block:: shell
sudo -u postgres psql funkwhale -c 'CREATE EXTENSION "unaccent";'
sudo -u postgres psql funkwhale -c 'CREATE EXTENSION "citext";'
Cache setup (Redis)
-------------------
Funkwhale also requires a cache server:
- To make the whole system faster, by caching network requests or database
queries
- To handle asynchronous tasks such as music import
On Debian-like distributions, a redis package is available, and you can
install it:
.. code-block:: shell
sudo apt-get install redis-server
On Arch Linux and its derivatives:
.. code-block:: shell
sudo pacman -S redis
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.
Installation
=============
============
Requirements
------------
......@@ -11,58 +11,9 @@ Regardless of your chosen installation method, the following requirements must b
.. note::
Because of the federated nature of Funkwhale, **we strongly recommend you not to change the Funkwhale domain after initial deployment**, as it is likely to break
Because of the federated nature of Funkwhale, **it is strongly recommended not to change the Funkwhale domain after initial deployment**, as it is likely to break
your installation.
Available installation methods
-------------------------------
Quick install
^^^^^^^^^^^^^
To install the latest version of Funkwhale on a recent Debian or Ubuntu server, run::
sudo apt-get update
sudo apt-get install curl
sudo sh -c "$(curl -sSL https://get.funkwhale.audio/)"
This installation script will ask you a few questions, install the required dependencies
and set up your instance.
Additional info:
- This script is based on our `Ansible role <https://dev.funkwhale.audio/funkwhale/ansible/>`_.
- By default, the script installs Nginx, PostgreSQL, Redis and Funkwhale itself but you can customize the installation procedure if you already have some of these services available on your machine
- Edit your pod configuration in ``/srv/funkwhale/ansible/playbook.yml`` and apply new configuration with ``sudo /srv/funkwhale/ansible/reconfigure``
- Upgrade is done using ``sh -c "$(curl -sSL https://get.funkwhale.audio/upgrade.sh)"``.
Alternative installation methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
We also offer Docker images, an installation guide for Debian 9 and Arch Linux, and `an
Ansible role <https://dev.funkwhale.audio/funkwhale/ansible/>`_.
.. toctree::
:maxdepth: 1
external_dependencies
debian
docker
systemd
non_amd64_architectures
Third-party packages
^^^^^^^^^^^^^^^^^^^^
Funkwhale packages are available for the following platforms:
- `YunoHost 3 <https://yunohost.org/>`_: https://github.com/YunoHost-Apps/funkwhale_ynh (kindly maintained by `@Jibec <https://github.com/Jibec>`_)
- ArchLinux (as an AUR package): if you'd rather use a package, check out this alternative installation method on ArchLinux: https://wiki.archlinux.org/index.php/Funkwhale (package and wiki kindly maintained by getzee)
- `NixOS <https://github.com/mmai/funkwhale-nixos>`_ (kindly maintained by @mmai)
- `Helm chart <https://gitlab.com/ananace/charts/>`_ to install Funkwhale on Kubernetes (kindly maintained by `@ananace <https://gitlab.com/ananace>`_)
- `HomelabOS <https://homelabos.com/docs/software/funkwhale/>`_
Project architecture
--------------------
......@@ -80,19 +31,18 @@ The project relies on the following components and services to work:
The synced clock is needed for federation purpose, to assess
the validity of incoming requests.
Hardware requirements
---------------------
Funkwhale is not especially CPU hungry. On a dockerized instance with 2 CPUs
and a few active users, the memory footprint is around ~500Mb::
and a few active users, the memory footprint is around 500Mb::
CONTAINER MEM USAGE
funkwhale_api_1 202.1 MiB
funkwhale_celerybeat_1 96.52 MiB
funkwhale_celeryworker_1 168.7 MiB
funkwhale_postgres_1 22.73 MiB
funkwhale_redis_1 1.496 MiB
funkwhale_api_1 202 MiB
funkwhale_celerybeat_1 96 MiB
funkwhale_celeryworker_1 168 MiB
funkwhale_postgres_1 22 MiB
funkwhale_redis_1 1 MiB
Some users have reported running Funkwhale on Raspberry Pis with a memory
consumption of less than 350 MiB.
......@@ -101,7 +51,7 @@ Thus, Funkwhale should run fine on commodity hardware, small hosting boxes and
Raspberry Pi. We lack real-world examples of such deployments, so don't hesitate
do give us your feedback (either positive or negative).
Check out :doc:`optimization` for advice on how to tune your instance on small
Check out :doc:`../admin/optimization` for advice on how to tune your instance on small
configurations.
Software requirements
......@@ -119,6 +69,55 @@ dependencies should be available in your distribution's repositories.
Funkwhale works only with Python >= 3.5, as we need support for async/await.
Older versions of Python are not supported.
Available installation methods
-------------------------------
Funkwhale can be installed using one of the following method:
- Quick install, the most straight forward way to get Funkwhale;
- Mono-container Docker installation;
- Multi-container Docker installation;
- Manual Debian and Arch Linux installation;
- `Ansible role <https://dev.funkwhale.audio/funkwhale/ansible/>`_.
Further, Funkwhale packages are available for the following platforms:
- `YunoHost 3 <https://yunohost.org/>`_: https://github.com/YunoHost-Apps/funkwhale_ynh (kindly maintained by `@Jibec <https://github.com/Jibec>`_)
- ArchLinux (as an AUR package): if you'd rather use a package, check out this alternative installation method on ArchLinux: https://wiki.archlinux.org/index.php/Funkwhale (package and wiki kindly maintained by getzee)
- `NixOS <https://github.com/mmai/funkwhale-nixos>`_ (kindly maintained by @mmai)
- `Helm chart <https://gitlab.com/ananace/charts/>`_ to install Funkwhale on Kubernetes (kindly maintained by `@ananace <https://gitlab.com/ananace>`_)
- `HomelabOS <https://homelabos.com/docs/software/funkwhale/>`_
Quick install
^^^^^^^^^^^^^
To install the latest version of Funkwhale on a recent Debian or Ubuntu server, run::
sudo apt-get update
sudo apt-get install curl
sudo sh -c "$(curl -sSL https://get.funkwhale.audio/)"
This installation script will ask you a few questions, install the required dependencies
and set up your instance.
Additional info:
- This script is based on our `Ansible role <https://dev.funkwhale.audio/funkwhale/ansible/>`_.
- By default, the script installs Nginx, PostgreSQL, Redis and Funkwhale itself but you can customize the installation procedure if you already have some of these services available on your machine
- Edit your pod configuration in ``/srv/funkwhale/ansible/playbook.yml`` and apply new configuration with ``sudo /srv/funkwhale/ansible/reconfigure``
- Upgrade is done using ``sh -c "$(curl -sSL https://get.funkwhale.audio/upgrade.sh)"``.
Alternative installation methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. toctree::
:maxdepth: 1
debian
docker
non_amd64_architectures
Running Funkwhale on the develop branch
---------------------------------------
......@@ -144,18 +143,20 @@ since you may have to apply manual actions for your instance to continue to work
.. _frontend-setup:
Frontend setup
---------------
Serving only the frontend
-------------------------
.. note::
You do not need to do this if you are deploying using Docker, as frontend files
are already included in the docker image.
You also do not need to do this if you are deploying manually on Debian or Arch, as this is covered by the corresponding documentation already.
Files for the web frontend are purely static and can simply be downloaded, unzipped and served from any webserver:
.. parsed-literal::
.. code-block:: shell
cd /srv/funkwhale
curl -L -o front.zip "https://dev.funkwhale.audio/funkwhale/funkwhale/builds/artifacts/|version|/download?job=build_front"
......@@ -163,24 +164,32 @@ Files for the web frontend are purely static and can simply be downloaded, unzip
.. _reverse-proxy-setup:
Reverse proxy
--------------
Reverse proxy configuration
---------------------------
In order to make Funkwhale accessible from outside your server and to play nicely with other applications on your machine, you should configure a reverse proxy.
We offer sample configurations for Nginx, Apache2 and Caddy.
.. note::
You can freely adapt the proposed configuration to your own needs, as we cannot
cover every use case with a single template, especially when it's related
to SSL configuration.
Nginx
^^^^^
Ensure you have a recent version of nginx on your server. On Debian-like system, you would have to run the following:
.. code-block:: bash
.. code-block:: shell
sudo apt-get update
sudo apt-get install nginx
On Arch Linux and its derivatives:
.. code-block:: bash
.. code-block:: shell
sudo pacman -S nginx
......@@ -188,11 +197,15 @@ To avoid configuration errors at this level, we will generate an nginx configura
using your .env file. This will ensure your reverse-proxy configuration always
match the application configuration and make upgrade/maintenance easier.
.. note::
The following commands need to be run as superuser.
On docker deployments, run the following commands:
.. parsed-literal::
.. code-block:: shell
export FUNKWHALE_VERSION="|version|"
# download the needed files
curl -L -o /etc/nginx/funkwhale_proxy.conf "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/funkwhale_proxy.conf"
curl -L -o /etc/nginx/sites-available/funkwhale.template "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/docker.proxy.template"
......@@ -209,7 +222,6 @@ On docker deployments, run the following commands:
On non-docker deployments, run the following commands:
.. parsed-literal::
export FUNKWHALE_VERSION="|version|"
......@@ -235,12 +247,6 @@ On non-docker deployments, run the following commands:
grep '${' /etc/nginx/sites-available/funkwhale.conf
.. note::
You can freely adapt the resulting file to your own needs, as we cannot
cover every use case with a single template, especially when it's related
to SSL configuration.
Finally, enable the resulting configuration:
.. code-block:: bash
......@@ -249,38 +255,30 @@ Finally, enable the resulting configuration:
.. warning::
If you plan to use to in-place import, ensure the alias value
If you plan to use in-place import, ensure the alias value
in the ``_protected/music`` location matches your MUSIC_DIRECTORY_SERVE_PATH
env var.
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
is the path used by `certbot <https://certbot.eff.org/docs/>`_ when generating certificates with Let's Encrypt.
In you already have a certificate you'd like to use, simply update the nginx configuration
and replace ``ssl_certificate`` and ``ssl_certificate_key`` values with the proper paths.
If you don't have one, comment or remove the lines starting with ``ssl_certificate`` and ``ssl_certificate_key``. You can then proceed to generate
a certificate, as shown below:
.. code-block:: shell
Finally, check that the configuration is valid with ``nginx -t`` then reload your nginx server with ``sudo systemctl reload nginx``.
# install certbot with nginx support
sudo apt install python-certbot-nginx
# generate the certificate
# (accept the terms of service if prompted)
sudo certbot --nginx -d yourfunkwhale.domain
This should create a valid certificate and edit the nginx configuration to use the new certificate.
.. note::
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
files than a Python process.
Reloading
:::::::::
However, we do want to ensure users have the right to access music files, and
it can't be done at the proxy's level. To tackle this issue, `we use
nginx's internal directive <http://nginx.org/en/docs/http/ngx_http_core_module.html#internal>`_.
Check the configuration is valid with ``nginx -t`` then reload your nginx server with ``sudo systemctl reload nginx``.
When the API receives a request on its music serving endpoint, it will check
that the user making the request can access the file. Then, it will return an empty
response with a ``X-Accel-Redirect`` header. This header will contain the path
to the file to serve to the user, and will be picked by nginx, but never sent
back to the client.
Using this technique, we can ensure music files are covered by the authentication
and permission policy of your instance, while remaining as performant
as possible.
Apache2
^^^^^^^
......@@ -312,11 +310,6 @@ You can tweak the configuration file according to your setup, especially the
TLS configuration. Otherwise, defaults should work if you followed the
installation guide.
.. note::
To obtain a certificate to enable HTTPS on your server, please refer to the note in
the nginx chapter above.
Check the configuration is valid with ``apache2ctl configtest``, and once you're
done, load the new configuration with ``service apache2 restart``.
......@@ -342,24 +335,36 @@ Caddy v1::
}
}
HTTPS configuration
^^^^^^^^^^^^^^^^^^^
About internal locations
^^^^^^^^^^^^^^^^^^^^^^^^
After configuring the reverse proxy, you need a SSL certificate to enable HTTPS on your server.
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
files than a Python process.
The default reverse proxy configuration assumes you have those available at ``/etc/letsencrypt/live/${FUNKWHALE_HOSTNAME}/``, which
is the path used by `certbot <https://certbot.eff.org/docs/>`_ when generating certificates with Let's Encrypt.
If you already have a certificate you would like to use, simply update the reverse proxy configuration
and replace the following values with the proper paths:
- For nginx: ``ssl_certificate`` and ``ssl_certificate_key``;
- For Apache2: ``SSLCertificateFile`` and ``SSLCertificateKeyFile``.
If you don't have one, comment or remove the lines starting with ``ssl_certificate`` and ``ssl_certificate_key`` for nginx, and ``SSLCertificateFile`` and ``SSLCertificateKeyFile`` for Apache2. You can then proceed to generate
a certificate, as shown below. These instructions are provided by `certbot <https://certbot.eff.org/instructions>`:
.. code-block:: shell
# install certbot
sudo snap install core; sudo snap refresh core
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
# if you are using nginx: generate the certificate
sudo certbot --nginx -d yourfunkwhale.domain
# if you are using Apache2: generate the certificate
sudo certbot --apache -d yourfunkwhale.domain
This creates a valid certificate and edit the nginx or Apache2 configuration to use the new certificate. The certificate will be automatically renewed when they expire.
However, we do want to ensure users have the right to access music files, and
it can't be done at the proxy's level. To tackle this issue, `we use
nginx's internal directive <http://nginx.org/en/docs/http/ngx_http_core_module.html#internal>`_.
When the API receives a request on its music serving endpoint, it will check
that the user making the request can access the file. Then, it will return an empty
response with a ``X-Accel-Redirect`` header. This header will contain the path
to the file to serve to the user, and will be picked by nginx, but never sent
back to the client.
Using this technique, we can ensure music files are covered by the authentication
and permission policy of your instance, while remaining as performant
as possible.
......@@ -42,7 +42,7 @@ guide.
Building the mono-container Docker image (funkwhale/all-in-one)
--------------------------------------------------------------
---------------------------------------------------------------
This image is intended to be used in conjunction with our :ref:`Mono-container installation guide <docker-mono-container>`.
guide.
......
Systemd configuration
----------------------
.. note::
All the command lines below should be executed as root.
Systemd offers a convenient way to manage your Funkwhale instance if you're
not using docker.
We'll see how to setup systemd to properly start a Funkwhale instance.
First, download the sample unitfiles:
.. parsed-literal::
curl -L -o "/etc/systemd/system/funkwhale.target" "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/funkwhale.target"
curl -L -o "/etc/systemd/system/funkwhale-server.service" "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/funkwhale-server.service"
curl -L -o "/etc/systemd/system/funkwhale-worker.service" "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/funkwhale-worker.service"
curl -L -o "/etc/systemd/system/funkwhale-beat.service" "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/funkwhale-beat.service"
This will download three unitfiles:
- ``funkwhale-server.service`` to launch the Funkwhale web server
- ``funkwhale-worker.service`` to launch the Funkwhale task worker
- ``funkwhale-beat.service`` to launch the Funkwhale task beat (this is for recurring tasks)
- ``funkwhale.target`` to easily stop and start all of the services at once
You can of course review and edit them to suit your deployment scenario
if needed, but the defaults should be fine.
Once the files are downloaded, reload systemd:
.. code-block:: shell
systemctl daemon-reload
And start the services:
.. code-block:: shell
systemctl start funkwhale.target
To ensure all Funkwhale processes are started automatically after a reboot, run:
.. code-block:: shell
systemctl enable funkwhale-server
systemctl enable funkwhale-worker
systemctl enable funkwhale-beat
You can check the statuses of all processes like this:
.. code-block:: shell
systemctl status funkwhale-\*
......@@ -16,8 +16,6 @@ Here is a (non-exhaustive) list of operations you can perform via the CLI:
.. contents:: Table of Contents
Installation
------------
......@@ -54,13 +52,6 @@ Here are a couple of commands you can try to get started:
# Search artists matching "zebra" on open.audio
funkwhale -H https://open.audio artists ls "zebra"
More examples
-------------
You should find enough in this reference document to start using the CLI on your own.
However, we've compiled :doc:`a list of example uses of the CLI <examples>` with advice and explanations, if you want to check it out ;)
Getting help
------------
......@@ -126,8 +117,8 @@ List of configuration options
| ``-q``, ``--quiet`` | ``FUNKWHALE_QUIET`` | ``true`` | Completely disable logging |
+--------------------------------------+------------------------------------------------+--------------------------------------------+---------------------------------------------------------------+
Listing results
---------------
Read commands
-------------
All commands that list results - such as ``funkwhale albums ls`` or ``funkwhale tracks ls`` - share similar behaviors and sets of arguments.
......@@ -238,8 +229,11 @@ The ``-i`` or ``--ids`` flag displays only the IDs of results, one per line::
This is especially useful in conjunction with other commands (like deletion commands) and piping.
Note that this is also technically equivalent to applying the ``--no-headers``, ``--format plain`` and ``--column ID`` flags.
Write commands
--------------
Deleting objects
----------------
^^^^^^^^^^^^^^^^
Some resources support deletion, via commands such as ``funkwhale libraries rm`` or ``funkwhale playlists rm``, followed by one or more IDs::
......@@ -250,3 +244,68 @@ By default, the ``rm`` command will ask for confirmation, but you can disable th
.. _API Documentation: https://docs.funkwhale.audio/swagger/
Examples
--------
Uploading local files
^^^^^^^^^^^^^^^^^^^^^
**Goal**: create a library and upload all MP3 files from ``~/Music`` to it
**Commands**::
funkwhale libraries create --name "My awesome library" --visibility me
# copy the returned UUID
funkwhale uploads create <UUID> ~/Music/**/*.mp3
Favorite an entire album
^^^^^^^^^^^^^^^^^^^^^^^^
**Goal**: retrieve all the tracks from an album and add these to your favorites
**Commands**::
# retrieve the album ID
funkwhale albums ls "The Slip"
# Copy the ID, then retrieve 100 pages of tracks from that album
# get only the IDs and pipe those to the favorite creation command
funkwhale tracks ls -f "album=<ID>" --ids --limit 100 \
| xargs funkwhale favorites tracks create
Mirror an artist discography locally
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
**Goal**: Download the discography of an artist locally, in the ``~/Music`` directory, in an ``Artist/Album/Track`` folder hierarchy
**Commands**::
# retrieve the artist ID
funkwhale artists ls "Nine Inch Nails"
# Copy the ID, then retrieve 100 pages of tracks from that artist
# get only the IDs and pipe those to the download command
funkwhale tracks ls -f "artist=<ID>" --ids --limit 100 \
| xargs funkwhale tracks download \
-f mp3 -d ~/Music -t "{artist}/{album}/{title}.{extension}"
Open a remote album in VLC
^^^^^^^^^^^^^^^^^^^^^^^^^^
**Goal**: Variation of the previous example, but instead of downloading an artist discography, we listen to an album in VLC
**Commands**::
# retrieve the album ID
funkwhale albums ls "The Slip"
# Copy the ID, then retrieve 100 pages of tracks from that album
# get only the IDs, download the corresponding tracks and pipe the audio
# directly to VLC
funkwhale tracks ls -f "album=<ID>" --ids --limit 100 \
| xargs funkwhale tracks download \
| vlc -
\ No newline at end of file
......@@ -33,7 +33,7 @@ Using Funkwhale
follow
apps
reports
../cli/index
cli
Troubleshooting Issues
----------------------
......
......@@ -3,11 +3,11 @@ Uploading Content To Funkwhale
To upload content to any Funkwhale instance, you need:
1. :doc:`An account on that instance <create>`
2. :ref:`Storage space <upload-storage>`
3. :ref:`A library <upload-library>` or :ref:`channel <upload-channel>`
4. :ref:`Properly tagged files <upload-tagging>`
5. :ref:`To upload your files <upload-upload>`
1. :doc:`An account on that instance <create>`;
2. :ref:`Storage space <upload-storage>`;
3. :ref:`A library <upload-library>` or :ref:`channel <upload-channel>`;
4. :ref:`Properly tagged files <upload-tagging>`;
5. To upload your files :ref:`to a library <upload_library>` or :ref:`to a channel <channel_upload>`.
.. _upload-storage:
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment