diff --git a/changes/changelog.d/456.feature b/changes/changelog.d/456.feature new file mode 100644 index 000000000..f05188e98 --- /dev/null +++ b/changes/changelog.d/456.feature @@ -0,0 +1,8 @@ +Make funkwhale themable by loading external stylesheets (#456) + +Custom themes for Funkwhale +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you ever wanted to give a custom look and feel to your instance, this is now possible. + +Check https://docs.funkwhale.audio/configuration.html#theming if you want to know more! diff --git a/docs/configuration.rst b/docs/configuration.rst index 3e7b5aa25..687447697 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -158,3 +158,79 @@ permissions are: There is no dedicated interface to manage users permissions, but superusers can login on the Django's admin at ``/api/admin/`` and grant permissions to users at ``/api/admin/users/user/``. + +Theming +------- + +Funkwhale supports custom themes, which are great if you want to personnalize the +look and feel of your instance. Theming is achieved by declaring +additionnal stylesheets you want to load in the front-end. + +Customize the settings +^^^^^^^^^^^^^^^^^^^^^^ + +In order to know what stylesheets to load, the front-end requests the following +url: ``https://your.instance/settings.json``. On typical deployments, this url +returns a 404 error, which is simply ignored. + +However, if you return the appropriate payload on this url, you can make the magic +work. We will store the necessary files in the ``/srv/funkwhale/custom`` directory: + +.. code-block:: shell + + cd /srv/funkwhale/ + mkdir custom + cat < custom/settings.json + { + "additionalStylesheets": ["/custom/custom.css"] + } + EOF + cat < custom/custom.css + body { + background-color: red; + } + EOF + +By executing the previous commands, you will end up with two files in your ``/srv/funkwhale/custom`` +directory: + +- ``settings.json`` will tell the front-end what stylesheets you want to load (``/custom/custom.css`` in this example) +- ``custom.css`` will hold your custom CSS + +The last step to make this work is to ensure both files are served by the reverse proxy. + +On nginx, add the following snippet to your vhost config:: + + location /settings.json { + alias /srv/funkwhale/custom/settings.json; + } + location /custom { + alias /srv/funkwhale/custom; + } + +On apache, use the following one:: + + Alias /settings.json /srv/funkwhale/custom/settings.json + Alias /custom /srv/funkwhale/custom + + + Options FollowSymLinks + AllowOverride None + Require all granted + + +Once done, reload your reverse proxy, refresh Funkwhale in your web browser, and you should see +a red background. + +.. note:: + + You can reference external urls as well in ``settings.json``, simply use + the full urls. Be especially careful with external urls as they may affect your users + privacy. + +.. warning:: + + Loading additional stylesheets and CSS rules can affect the performance and + usability of your instance. If you encounter issues with the interfaces and use + custom stylesheets, try to disable those to ensure the issue is not caused + by your customizations. diff --git a/front/config/index.js b/front/config/index.js index d10f35e91..44a3b640b 100644 --- a/front/config/index.js +++ b/front/config/index.js @@ -29,6 +29,9 @@ module.exports = { assetsSubDirectory: 'static', assetsPublicPath: '/', proxyTable: { + '/settings.json': { + target: 'http://127.0.0.1:8000/static/', + }, '**': { target: 'http://nginx:6001', changeOrigin: true, diff --git a/front/src/App.vue b/front/src/App.vue index 58ed698aa..8b1ac775a 100644 --- a/front/src/App.vue +++ b/front/src/App.vue @@ -1,5 +1,7 @@