docker.rst 7.4 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
    # Remove this if you expose the container directly on ports 80/443
    echo "NESTED_PROXY=1" >> .env
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
88
89

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``

90
.. note::
91

92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
    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
116

117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

    You can use the following docker-compose file to make the management process easier:

    .. code-block:: yaml

        version: "3"

        services:
          funkwhale:
            container_name: funkwhale
            restart: unless-stopped
            # add the version number in your .env file, or hardcode it
            image: funkwhale/all-in-one:${FUNKWHALE_VERSION}
            env_file: .env
            environment:
              # adapt to the pid/gid that own /srv/funkwhale/data
              - PUID=1000
              - PGID=1000
            volumes:
              - /srv/funkwhale/data:/data
              - /path/to/your/music/dir:/music:ro
            ports:
              - "5000:80"


142
143
144
145
146
.. _docker-multi-container:

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

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

149
150
151
152
153
154
Export the version you want to deploy:

.. parsed-literal::

    export FUNKWHALE_VERSION="|version|"

155
156
Download the sample docker-compose file:

157
.. parsed-literal::
158

Nathanael's avatar
Nathanael committed
159
    mkdir /srv/funkwhale
160
    cd /srv/funkwhale
161
    mkdir nginx
162
    curl -L -o nginx/funkwhale.template "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/docker.nginx.template"
163
    curl -L -o nginx/funkwhale_proxy.conf "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/docker.funkwhale_proxy.conf"
164
    curl -L -o docker-compose.yml "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/docker-compose.yml"
165

Paul Walko's avatar
Paul Walko committed
166
At this point, the architecture of ``/srv/funkwhale``  should look like that:
Nathanael's avatar
Nathanael committed
167
168
169
170
171
172
173
174
175

::

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

176
177
Create your env file:

178
.. parsed-literal::
179

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

Nathanael's avatar
Nathanael committed
184
185
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.
186
187
188
189
190
191
192
193
194
195
196
197
198
199

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

200
201
202
203
204
205
206
207
208
.. 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.

209
210
211
212
213
214
215
216
217
218
219
220
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

221
Now, you just need to configure your :ref:`reverse-proxy <reverse-proxy-setup>`. Don't worry, it's quite easy.
222
223
224
225

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

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