docker.rst 6.6 KB
Newer Older
1
Docker installation
2
===================
3

Reg's avatar
Reg committed
4
Docker is the easiest way to get a Funkwhale instance up and running.
5

6 7 8 9 10
We support two types of Docker deployments:

- :ref:`Mono-container <docker-mono-container>`: all processes live in the same container (database, nginx, redis, etc.). It's easier to deploy and to integrate with container management systems like Portainer. However, it's not possible to scale this type of deployment on multiple servers.
- :ref:`Multi-container <docker-multi-container>`: each process lives in a dedicated container. This setup is more involved but also more flexible and scalable.

11 12 13 14 15 16
.. note::

    We do not distribute Docker images for non-amd64 architectures yet. However, :doc:`you can easily build
    those images yourself following our instructions <non_amd64_architectures>`, and come back to this installation guide once
    the build is over.

17 18 19 20 21 22 23 24 25 26 27
.. _docker-mono-container:

Mono-container installation
---------------------------

.. note::

    This installation method was contributed by @thetarkus, at https://github.com/thetarkus/docker-funkwhale

First, ensure you have `Docker <https://docs.docker.com/engine/installation/>`_ installed.

28
Create the user and the directory:
29

30 31 32 33
.. code-block:: shell

    sudo useradd -r -s /usr/bin/nologin -d /srv/funkwhale -m funkwhale
    sudo adduser funkwhale docker
34 35
    cd /srv/funkwhale

36 37 38 39 40 41
Log in as the newly created user from now on:

.. code-block:: shell

    sudo -u funkwhale -H bash

42 43 44 45 46 47 48 49 50 51 52 53
Export the version you want to deploy:

.. parsed-literal::

    export FUNKWHALE_VERSION="|version|"

Create an env file to store a few important configuration options:

.. code-block:: shell

    touch .env
    echo "FUNKWHALE_HOSTNAME=yourdomain.funkwhale" >> .env
54 55
    echo "FUNKWHALE_PROTOCOL=https" >> .env  # or http
    echo "DJANGO_SECRET_KEY=$(openssl rand -hex 45)" >> .env  # generate and store a secure secret key for your instance
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87

Then start the container:

.. code-block:: shell

    docker run \
        --name=funkwhale \
        --restart=unless-stopped \
        --env-file=/srv/funkwhale/.env \
        -v /srv/funkwhale/data:/data \
        -v /path/to/your/music/dir:/music:ro \
        -e PUID=$UID \
        -e PGID=$GID \
        -p 5000:80 \
        -d \
        funkwhale/all-in-one:$FUNKWHALE_VERSION

.. note::

    - ``-e PUID`` and ``-e PGID`` are optional but useful to prevent permission issues with docker volumes
    - ``-v /path/to/your/music/dir`` should point to a path on your host were is located music you want to import in your Funkwhale instance. You can safely remove the volume if you don't want to import music that way.

Your container should start in the background, and your instance be available at ``yourip:5000`` shortly.

You will need an admin account to login and manage your account, create one using the following command: ``docker exec -it funkwhale manage createsuperuser``

Useful commands:

- You can examine the logs by running ``docker logs -f --tail=50 funkwhale``
- You can start and stop your instance using ``docker start funkwhale`` and ``docker stop funkwhale``, respectively
- To have a better idea of the resource usage of your instance (CPU, memory), run ``docker stats funkwhale``

88
.. note::
89

90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
    The container will not pick up changes made in .env file automatically.
    In order to load new configuration, run:

    .. parsed-literal::

        export FUNKWHALE_VERSION="|version|"

    .. code-block:: shell

        # stop and remove the existing container
        docker stop funkwhale
        docker rm funkwhale
        # relaunch a new container
        docker run \
            --name=funkwhale \
            --restart=unless-stopped \
            --env-file=/srv/funkwhale/.env \
            -v /srv/funkwhale/data:/data \
            -v /path/to/your/music/dir:/music:ro \
            -e PUID=$UID \
            -e PGID=$GID \
            -p 5000:80 \
            -d \
            funkwhale/all-in-one:$FUNKWHALE_VERSION
114 115 116 117 118 119

.. _docker-multi-container:

Multi-container installation
----------------------------

Nathanael's avatar
Nathanael committed
120
First, ensure you have `Docker <https://docs.docker.com/engine/installation/>`_ and `docker-compose <https://docs.docker.com/compose/install/>`_ installed.
121

122 123 124 125 126 127
Export the version you want to deploy:

.. parsed-literal::

    export FUNKWHALE_VERSION="|version|"

128 129
Download the sample docker-compose file:

130
.. parsed-literal::
131

Nathanael's avatar
Nathanael committed
132
    mkdir /srv/funkwhale
133
    cd /srv/funkwhale
134
    mkdir nginx
135
    curl -L -o nginx/funkwhale.template "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/docker.nginx.template"
136
    curl -L -o nginx/funkwhale_proxy.conf "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/docker.funkwhale_proxy.conf"
137
    curl -L -o docker-compose.yml "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/docker-compose.yml"
138

Paul Walko's avatar
Paul Walko committed
139
At this point, the architecture of ``/srv/funkwhale``  should look like that:
Nathanael's avatar
Nathanael committed
140 141 142 143 144 145 146 147 148

::

    .
    ├── docker-compose.yml
    └── nginx
        ├── funkwhale_proxy.conf
        └── funkwhale.template

149 150
Create your env file:

151
.. parsed-literal::
152

153
    curl -L -o .env "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/env.prod.sample"
154
    sed -i "s/FUNKWHALE_VERSION=latest/FUNKWHALE_VERSION=$FUNKWHALE_VERSION/" .env
Nathanael's avatar
Nathanael committed
155
    sudo nano .env
156

Nathanael's avatar
Nathanael committed
157 158
Ensure to edit it to match your needs (this file is heavily commented), in particular ``DJANGO_SECRET_KEY`` and ``FUNKWHALE_HOSTNAME``.
You should take a look at the `configuration reference <https://docs.funkwhale.audio/configuration.html#configuration-reference>`_ for more detailed information regarding each setting.
159 160 161 162 163 164 165 166 167 168 169 170 171 172

Then, you should be able to pull the required images:

.. code-block:: bash

    docker-compose pull

Run the database container and the initial migrations:

.. code-block:: bash

    docker-compose up -d postgres
    docker-compose run --rm api python manage.py migrate

173 174 175 176 177 178 179 180 181
.. warning::

    You may sometimes get the following warning while applying migrations::

        "Your models have changes that are not yet reflected in a migration, and so won't be applied."

    This is a warning, not an error, and it can be safely ignored.
    Never run the ``makemigrations`` command yourself.

182 183 184 185 186 187 188 189 190 191 192 193
Create your admin user:

.. code-block:: bash

    docker-compose run --rm api python manage.py createsuperuser

Then launch the whole thing:

.. code-block:: bash

    docker-compose up -d

194
Now, you just need to configure your :ref:`reverse-proxy <reverse-proxy-setup>`. Don't worry, it's quite easy.
195 196 197 198

About music acquisition
-----------------------

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