README.md 7.44 KB
Newer Older
Eliot Berriot's avatar
Eliot Berriot committed
1
2
Funkwhale ansible role
======================
Eliot Berriot's avatar
Eliot Berriot committed
3

Eliot Berriot's avatar
Eliot Berriot committed
4
An ansible role to install and update [Funkwhale](https://funkwhale.audio).
Eliot Berriot's avatar
Eliot Berriot committed
5

Eliot Berriot's avatar
Eliot Berriot committed
6
7
8
9
10
11
12
13
14
15
Summary
-------

Using this role, you can install and upgrade a Funkwhale pod, closely matching our [standard installation guide](https://docs.funkwhale.audio/installation/debian.html). The role will take care of:

- Installing and configure dependencies and packages
- Install and configure PostgreSQL, Redis and Nginx (optional)
- Install and configure Funkwhale and it's dependencies
- Install and configure a SSL certificate with Let's Encrypt (optional)

16
17
18
19
20
21
22
23
24
25
26
27
Philosophy
----------

This role strives to:

- Work out-of-the box by default
- Be modular and lightweight
- Avoid dependencies on other ansible roles
- Allow further customization
- Allow running multiple Funkwhale instances on the same host
- Avoid messing with existing software and apps on the server

28
29
Installation and usage
----------------------
Eliot Berriot's avatar
Eliot Berriot committed
30

31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
Install ansible:

```
pip install --user ansible
```

Create a directory for ansible files:

    mkdir ~/ansible-funkwhale
    cd ansible-funkwhale

Create a playbook requirements and inventory file:

    touch requirements.yml
    touch playbook.yml
    touch inventory.ini
Eliot Berriot's avatar
Eliot Berriot committed
47
    touch ansible.cfg
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

Add the following to `requirements.yml`:

```
- src: git+https://dev.funkwhale.audio/funkwhale/ansible
  name: funkwhale
  version: master
```

Install the role:

```
ansible-galaxy install -r requirements.yml
```

Eliot Berriot's avatar
Eliot Berriot committed
63
64
65
66
67
68
69
70
71
Add the following to `ansible.cfg`:

```
[defaults]
# Needed to use become with unprevileged users,
# see https://docs.ansible.com/ansible/latest/user_guide/become.html#becoming-an-unprivileged-user
allow_world_readable_tmpfiles=true
```

72
Add the following to `playbook.yml`:
Eliot Berriot's avatar
Eliot Berriot committed
73
74

```yaml
75
- hosts: funkwhale-servers
Eliot Berriot's avatar
Eliot Berriot committed
76
77
78
79
80
81
  roles:
    - role: funkwhale
      funkwhale_hostname: yourdomain.funkwhale
      funkwhale_version: 0.18.3
      funkwhale_letsencrypt_email: contact@youremail.com
```
Eliot Berriot's avatar
Eliot Berriot committed
82

Eliot Berriot's avatar
Eliot Berriot committed
83
See below for a full documentation on available variables.
Eliot Berriot's avatar
Eliot Berriot committed
84

85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
Add your server to `inventory.ini`:

```ini
[funkwhale-servers]
your-server-ip-or-domain
```

Launch the installation (in check mode, so nothing is applied):

```
ansible-playbook --ask-become-pass -i inventory.ini playbook.yml --check --diff
```
*On some hosts, you may need to install the `python-apt` package for check mode to work*.

This command will show you the changes that would be applied to your system. If you are confortable with them,
rerun the same command without the `--check` flag.


Eliot Berriot's avatar
Eliot Berriot committed
103
104
105
Role Variables
--------------

Eliot Berriot's avatar
Eliot Berriot committed
106
107
108
109
110
111
112
113
114
**Required variables**

| name                          | Example                       | Description                                   |
| ----------------------------- | ----------------------------- | --------------------------------------------- |
| `funkwhale_hostname`          | `yourdomain.funkwhale`        | The domain name of your Funkwhale pod         |
| `funkwhale_version`           | `0.18.3`                      | The version to install/upgrade to. You can also use `develop` to run the development branch         |
| `funkwhale_letsencrypt_email` | `contact@youremail.com`       | The email to associate with your Let's Encrypt certificate (not needed if you set `funkwhale_letsencrypt_enabled: false`, see below) |

**Optional variables**
Eliot Berriot's avatar
Eliot Berriot committed
115
116


Eliot Berriot's avatar
Eliot Berriot committed
117
118
119
120
121
122
123
124
125
126
| name                                    | Default                       | Description                                   |
| --------------------------------------- | ----------------------------- | --------------------------------------------- |
| `funkwhale_api_ip`                      | `127.0.0.1`                   | IP adress to bind the Funkwhale server to |
| `funkwhale_api_port`                    | `5000`                        | Port to bind the Funkwhale server to |
| `funkwhale_config_path`                 | `/srv/funkwhale/config`       | Path to Funkwhale's configuration directory |
| `funkwhale_database_managed`            | `true`                        | If `true`, the role will manage the database server and Funkwhale's database  |
| `funkwhale_database_name`               | `funkwhale`                   | Name of the Funkwhale database to use |
| `funkwhale_database_user`               | `funkwhale`                   | Postgresql username to login as |
| `funkwhale_env_vars`                    | `[]`                          | List of environment variables to append to the generated `.env` file. Example: `["AWS_ACCESS_KEY_ID=myawsid", "AWS_SECRET_ACCESS_KEY=myawskey"]` |
| `funkwhale_external_storage_enabled`    | `false`                       | If `true`, set up the proper configuration to use an extenal storage for media files |
127
| `funkwhale_disable_django_admin`        | `false`                       | If `true`, returns a 403 (Forbidden) for `/api/admin` |
Eliot Berriot's avatar
Eliot Berriot committed
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
| `funkwhale_install_path`                | `/srv/funkwhale`              | Path were frontend, api and virtualenv files should be stored (**no trailing slash**) |
| `funkwhale_letsencrypt_certbot_flags`   | `null`                        | Additional flags to pass to `certbot` |
| `funkwhale_letsencrypt_enabled`         | `true`                        | If `true`, will configure SSL with certbot and Let's Encrypt |
| `funkwhale_media_path`                  | `/srv/funkwhale/data/media`   | Path were audio and uploaded files should be stored (**no trailing slash**)  |
| `funkwhale_music_path`                  | `/srv/funkwhale/data/music`   | Path to your existing music library, to use with [CLI import](https://docs.funkwhale.audio/admin/importing-music.html) (**no trailing slash**) |
| `funkwhale_nginx_managed`               | `true`                        | If `true`, will install and configure nginx |
| `funkwhale_nginx_max_body_size`         | `100M`                        | Value of nginx's `max_body_size` parameter to use |
| `funkwhale_protocol`                    | `https`                       | If set to `https`, will configure Funkwhale and Nginx to work behind HTTPS. Use `http` to completely disable SSL. |
| `funkwhale_redis_managed`               | `true`                        | If `true`, will install and configure redis |
| `funkwhale_ssl_cert_path`               | ``                            | Path to an existing SSL certificate to use (use in combination with `funkwhale_letsencrypt_enabled: false`) |
| `funkwhale_ssl_key_path`                | ``                            | Path to an existing SSL key to use (use in combination with `funkwhale_letsencrypt_enabled: false`) |
| `funkwhale_static_path`                 | `/srv/funkwhale/data/static`  | Path were Funkwhale static files should be stored |
| `funkwhale_systemd_after`               | `redis.service postgresql.service` | Configuration used for Systemd `After=` directive. Modify it if you have a database or redis server on a separate host   |
| `funkwhale_systemd_service_name`        | `funkwhale`                   | Name of the generated Systemd service, e.g when calling `systemctl start <xxx>` |
| `funkwhale_username`                    | `funkwhale`                   | Username of the system user and owner of Funkwhale data, files and configuration |
Eliot Berriot's avatar
Eliot Berriot committed
143

Eliot Berriot's avatar
Eliot Berriot committed
144
145
Supported platforms
-------------------
Eliot Berriot's avatar
Eliot Berriot committed
146

Eliot Berriot's avatar
Eliot Berriot committed
147
148
149
150
151
- Debian 9
- More to come

Dependencies
------------
Eliot Berriot's avatar
Eliot Berriot committed
152

Eliot Berriot's avatar
Eliot Berriot committed
153
This roles has no other dependencies.
Eliot Berriot's avatar
Eliot Berriot committed
154

155
156
157
158
159
160
Tests
-----

This role is tested using [molecule](https://molecule.readthedocs.io/en/stable/).
We don't have CI yet, but you can run the tests with `molecule test`.

Eliot Berriot's avatar
Eliot Berriot committed
161
162
163
164
165
166
Todo
----

- Backups
- Superuser creation

Eliot Berriot's avatar
Eliot Berriot committed
167
168
169
License
-------

Eliot Berriot's avatar
Eliot Berriot committed
170
AGPL3
Eliot Berriot's avatar
Eliot Berriot committed
171
172
173
174

Author Information
------------------

Eliot Berriot's avatar
Eliot Berriot committed
175
Contact us at https://funkwhale.audio/community/