docker.rst 7.38 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
.. _docker-mono-container:

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

.. note::

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

26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
These are the installation steps:

1. Install docker
2. Create ``funkwhale`` user
3. Create ``.env`` file
4. Create ``docker-compose.yml`` file
5. Start Funkwhale service

Install docker
~~~~~~~~~~~~~~

Ensure you have `Docker <https://docs.docker.com/engine/installation/>`_ and `docker-compose <https://docs.docker.com/compose/install/>`_ installed.

Create ``funkwhale`` user
~~~~~~~~~~~~~~~~~~~~~~~~~
41

42
Create the user and the directory:
43

44
45
.. code-block:: shell

46
    sudo useradd -r -s /usr/bin/nologin -m -d /srv/funkwhale -U -G docker funkwhale
47
48
    cd /srv/funkwhale

49
50
51
52
53
54
Log in as the newly created user from now on:

.. code-block:: shell

    sudo -u funkwhale -H bash

55
56
Create ``.env`` file
~~~~~~~~~~~~~~~~~~~~
57

Creak's avatar
Creak committed
58
Create a ``.env`` file to store a few important configuration options:
59
60
61
62

.. code-block:: shell

    touch .env
63
    chmod 600 .env  # reduce permissions on the .env file since it contains sensitive data
64
    cat > .env << EOF
65
66
67
68
69
70
71
72
73
74
75
76
    # Replace 'your.funkwhale.example' with your actual domain
    FUNKWHALE_HOSTNAME=your.funkwhale.example
    # Protocol may also be: http
    FUNKWHALE_PROTOCOL=https
    # This limits the upload size
    NGINX_MAX_BODY_SIZE=100M
    # Bind to localhost
    FUNKWHALE_API_IP=127.0.0.1
    # Container port you want to expose on the host
    FUNKWHALE_API_PORT=5000
    # Generate and store a secure secret key for your instance
    DJANGO_SECRET_KEY=$(openssl rand -hex 45)
77
    # Remove this if you expose the container directly on ports 80/443
78
    NESTED_PROXY=1
79
80
81
82
83
    EOF

Create ``docker-compose.yml`` file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Creak's avatar
Creak committed
84
85
86
Create a ``docker-compose.yml`` file to set up the containers:

.. parsed-literal::
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

    version: "3"
    services:
      funkwhale:
        container_name: funkwhale
        restart: unless-stopped
        # change version number here when you want to do an upgrade
        image: funkwhale/all-in-one:|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"
105

106
.. note::
107

Creak's avatar
Creak committed
108
    - The version can be changed (after ``funkwhale/all-in-one:``), `select the version <https://hub.docker.com/r/funkwhale/all-in-one/tags>`_ you want to deploy.
109
110
    - ``PUID`` and ``PGID`` are optional but useful to prevent permission issues with docker volumes
    - ``/path/to/your/music/dir`` should point to a path on your host where music you would like to import is located. You can safely remove the volume if you don't want to import music that way.
111

112
113
Start Funkwhale service
~~~~~~~~~~~~~~~~~~~~~~~
114

115
Start the container:
116

117
.. code-block:: shell
118

119
    docker-compose up -d
120
121
122
123
124
125
126

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:

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

131
Now, you just need to configure your :ref:`reverse-proxy <reverse-proxy-setup>`. Don't worry, it's quite easy.
132
133
134
135
136
137

.. _docker-multi-container:

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

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

140
Export the `version you want <https://hub.docker.com/r/funkwhale/all-in-one/tags>`_ to deploy (e.g., ``0.21``):
141
142
143
144
145

.. parsed-literal::

    export FUNKWHALE_VERSION="|version|"

146
147
Download the sample docker-compose file:

148
.. parsed-literal::
149

Nathanael's avatar
Nathanael committed
150
    mkdir /srv/funkwhale
151
    cd /srv/funkwhale
152
    mkdir nginx
153
154
155
    curl -L -o nginx/funkwhale.template "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/${FUNKWHALE_VERSION}/deploy/docker.nginx.template"
    curl -L -o nginx/funkwhale_proxy.conf "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/${FUNKWHALE_VERSION}/deploy/docker.funkwhale_proxy.conf"
    curl -L -o docker-compose.yml "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/${FUNKWHALE_VERSION}/deploy/docker-compose.yml"
156

Paul Walko's avatar
Paul Walko committed
157
At this point, the architecture of ``/srv/funkwhale``  should look like that:
Nathanael's avatar
Nathanael committed
158
159
160
161
162
163
164
165
166

::

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

167
168
Create your env file:

169
.. parsed-literal::
170

171
    curl -L -o .env "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/${FUNKWHALE_VERSION}/deploy/env.prod.sample"
172
    sed -i "s/FUNKWHALE_VERSION=latest/FUNKWHALE_VERSION=$FUNKWHALE_VERSION/" .env
173
    chmod 600 .env  # reduce permissions on the .env file since it contains sensitive data
Nathanael's avatar
Nathanael committed
174
    sudo nano .env
175

176

Nathanael's avatar
Nathanael committed
177
178
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.
179
180
181
182
183
184
185
186
187
188
189
190
191
192

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

193
194
195
196
197
198
199
200
201
.. 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.

202
203
204
205
206
207
208
209
210
211
212
213
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

214
Now, you just need to configure your :ref:`reverse-proxy <reverse-proxy-setup>`. Don't worry, it's quite easy.
215
216
217
218

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

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