index.rst 12.5 KB
Newer Older
1 2 3
Installation
=============

4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
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
23
- Edit your pod configuration in ``/srv/funkwhale/ansible/playbook.yml`` and apply new configuration with ``sudo /srv/funkwhale/ansible/reconfigure``
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
- 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)
Eliot Berriot's avatar
Eliot Berriot committed
50
- `Helm chart <https://gitlab.com/ananace/charts/>`_ to install Funkwhale on Kubernetes (kindly maintained by `@ananace <https://gitlab.com/ananace>`_)
51

52 53 54 55 56 57 58 59
Project architecture
--------------------

The project relies on the following components and services to work:

- A web application server (Python/Django/Gunicorn)
- A PostgreSQL database to store application data
- A redis server to store cache and tasks data
Paul Walko's avatar
Paul Walko committed
60
- A celery worker to run asynchronous tasks (such as music import)
61
- A celery scheduler to run recurrent tasks
62 63 64 65 66 67
- A `ntp-synced clock <https://wiki.debian.org/NTP>`_ to ensure federation is working seamlessly

.. note::

    The synced clock is needed for federation purpose, to assess
    the validity of incoming requests.
68

69 70 71 72

Hardware requirements
---------------------

73 74
Funkwhale is not especially CPU hungry. On a dockerized instance with 2 CPUs
and a few active users, the memory footprint is around ~500Mb::
75 76 77 78 79 80 81 82

   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

83
Some users have reported running Funkwhale on Raspberry Pis with a memory
Eliot Berriot's avatar
Typo  
Eliot Berriot committed
84
consumption of less than 350MiB.
85

86
Thus, Funkwhale should run fine on commodity hardware, small hosting boxes and
Paul Walko's avatar
Paul Walko committed
87
Raspberry Pi. We lack real-world examples of such deployments, so don't hesitate
88 89
do give us your feedback (either positive or negative).

Paul Walko's avatar
Paul Walko committed
90
Check out :doc:`optimization` for advice on how to tune your instance on small
91 92
configurations.

93 94 95 96 97 98 99 100 101 102 103 104
Software requirements
---------------------

Software requirements will vary depending of your installation method. For
Docker-based installations, the only requirement will be an Nginx reverse-proxy
that will expose your instance to the outside world.

If you plan to install your Funkwhale instance without Docker, most of the
dependencies should be available in your distribution's repositories.

.. note::

Paul Walko's avatar
Paul Walko committed
105
   Funkwhale works only with Python >= 3.5, as we need support for async/await.
106 107
   Older versions of Python are not supported.

108 109 110
Running Funkwhale on the develop branch
---------------------------------------

111
Traditional deployments are done using tagged releases. However, you
112
may want to benefit from the latest changes available, or to help detect
113 114 115 116 117 118
bugs before they are included in actual releases.

To do that, you'll need to run your instance on the develop branch,
which contains all the unreleased changes and features of the next version.

Please take into account that the develop branch
119
may be unstable and will contain bugs that may affect the well-being of your
120
instance. If you are comfortable with that, you need to backup at least your database
121
before pulling the latest changes from the develop branch.
122 123 124 125 126 127

Otherwise, the deployment process is similar to deploying with releases.
You simply need to use ``export FUNKWHALE_VERSION=develop``
in the installation and upgrade process instead of a real version number,
as we build artifacts on the development branch the same way we do for releases.

128
It's also recommended to check out the `develop release notes <https://dev.funkwhale.audio/funkwhale/funkwhale/blob/develop/changes/notes.rst>`_ before upgrading,
129 130
since you may have to apply manual actions for your instance to continue to work. Such actions are labelled with ``[manual action required]`` in the releases notes.

131 132 133 134 135
.. _frontend-setup:

Frontend setup
---------------

136 137 138 139 140 141
.. note::

    You do not need to do this if you are deploying using Docker, as frontend files
    are already included in the docker image.


142 143
Files for the web frontend are purely static and can simply be downloaded, unzipped and served from any webserver:

144
.. parsed-literal::
145 146

    cd /srv/funkwhale
Eliot Berriot's avatar
Eliot Berriot committed
147
    curl -L -o front.zip "https://dev.funkwhale.audio/funkwhale/funkwhale/builds/artifacts/|version|/download?job=build_front"
148 149 150 151 152 153 154
    unzip front.zip

.. _reverse-proxy-setup:

Reverse proxy
--------------

Reg's avatar
Reg committed
155
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.
156 157 158 159

Nginx
^^^^^

Reg's avatar
Reg committed
160
Ensure you have a recent version of nginx on your server. On Debian-like system, you would have to run the following:
161 162 163

.. code-block:: bash

Reg's avatar
Reg committed
164 165
    sudo apt-get update
    sudo apt-get install nginx
166

167 168 169 170 171 172
On Arch Linux and its derivatives:

.. code-block:: bash

    sudo pacman -S nginx

173 174 175 176
To avoid configuration errors at this level, we will generate an nginx configuration
using your .env file. This will ensure your reverse-proxy configuration always
match the application configuration and make upgrade/maintenance easier.

Renon's avatar
Renon committed
177
On docker deployments, run the following commands:
178

179
.. parsed-literal::
180

181
    export FUNKWHALE_VERSION="|version|"
182
    # download the needed files
183
    curl -L -o /etc/nginx/funkwhale_proxy.conf "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/funkwhale_proxy.conf"
184 185 186
    curl -L -o /etc/nginx/sites-available/funkwhale.template "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/docker.proxy.template"

.. code-block:: shell
187 188 189 190 191 192

    # create a final nginx configuration using the template based on your environment
    set -a && source /srv/funkwhale/.env && set +a
    envsubst "`env | awk -F = '{printf \" $%s\", $$1}'`" \
        < /etc/nginx/sites-available/funkwhale.template \
        > /etc/nginx/sites-available/funkwhale.conf
Eliot Berriot's avatar
Eliot Berriot committed
193

Eliot Berriot's avatar
Eliot Berriot committed
194
    ln -s /etc/nginx/sites-available/funkwhale.conf /etc/nginx/sites-enabled/
195

Renon's avatar
Renon committed
196
On non-docker deployments, run the following commands:
197

198 199 200 201

.. parsed-literal::

    export FUNKWHALE_VERSION="|version|"
202 203

    # download the needed files
204 205 206 207
    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/nginx.template"

.. code-block:: shell
208 209 210 211 212 213

    # create a final nginx configuration using the template based on your environment
    set -a && source /srv/funkwhale/config/.env && set +a
    envsubst "`env | awk -F = '{printf \" $%s\", $$1}'`" \
        < /etc/nginx/sites-available/funkwhale.template \
        > /etc/nginx/sites-available/funkwhale.conf
Eliot Berriot's avatar
Eliot Berriot committed
214

Eliot Berriot's avatar
Eliot Berriot committed
215
    ln -s /etc/nginx/sites-available/funkwhale.conf /etc/nginx/sites-enabled/
216 217 218

.. note::

219
    The resulting file should not contain any variables such as ``${FUNKWHALE_HOSTNAME}``.
220 221 222 223 224 225 226 227 228 229 230 231 232
    You can check that using this command::

        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
233

Hazmo's avatar
Hazmo committed
234
    ln -s /etc/nginx/sites-available/funkwhale.conf /etc/nginx/sites-enabled/
235

236 237 238 239 240 241
.. warning::

    If you plan to use to in-place import, ensure the alias value
    in the ``_protected/music`` location matches your MUSIC_DIRECTORY_SERVE_PATH
    env var.

242 243
HTTPS Configuration
:::::::::::::::::::
244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269

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

    # 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.

Reloading
:::::::::

Check the configuration is valid with ``nginx -t`` then reload your nginx server with ``sudo systemctl reload nginx``.

270

271 272 273
Apache2
^^^^^^^

274 275 276 277 278 279
.. note::

    These instructions are for Debian only.
    For Arch Linux please refer to the `Arch Linux wiki <https://wiki.archlinux.org/index.php/Apache>`_.

Ensure you have a recent version of Apache2 installed on your server.
280 281
You'll also need the following dependencies::

Reg's avatar
Reg committed
282
   sudo apt-get install libapache2-mod-xsendfile
283

284 285 286 287
Add the following to your ``.env`` file::

    REVERSE_PROXY_TYPE=apache2

288
Then restart Funkwhale. This is needed to ensure Funkwhale provides proper headers for media file serving.
289

290 291 292 293
Then, download our sample virtualhost file:

.. parsed-literal::

Eliot Berriot's avatar
Eliot Berriot committed
294
    curl -L -o /etc/apache2/sites-available/funkwhale.conf "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/apache.conf"
295 296 297
    ln -s /etc/apache2/sites-available/funkwhale.conf /etc/apache2/sites-enabled/

You can tweak the configuration file according to your setup, especially the
298
TLS configuration. Otherwise, defaults should work if you followed the
299 300
installation guide.

301 302 303 304 305
.. note::

    To obtain a certificate to enable HTTPS on your server, please refer to the note in
    the nginx chapter above.

306 307
Check the configuration is valid with ``apache2ctl configtest``, and once you're
done, load the new configuration with ``service apache2 restart``.
308

309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324
Caddy
^^^^^

If you're using Caddy as a reverse proxy in front of your docker containers (either mono or multi-container setup),
you can use the following configuration::

    yourdomain.funkwhale {
        proxy / 127.0.0.1:5000 {
            transparent
            websocket
            header_upstream X-Forwarded-Host {host}:{server_port}
        }
    }



325
About internal locations
326
^^^^^^^^^^^^^^^^^^^^^^^^
327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342

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.

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
343
and permission policy of your instance, while remaining as performant
344
as possible.