Skip to content
Snippets Groups Projects
Commit 13d08116 authored by Agate's avatar Agate 💬
Browse files

Documentation for .env variables

parent a6777973
No related branches found
No related tags found
No related merge requests found
Expand all Hide whitespace changes
Inline Side-by-side
.gitlab-ci.yml
+ 1
− 1
View file @ 13d08116
......@@ -71,7 +71,7 @@ review_docs:
- cd docs
- apt-get update
- apt-get install -y graphviz
- pip install sphinx sphinx_rtd_theme
- pip install sphinx sphinx_rtd_theme django-environ django
script:
- ./build_docs.sh
cache:
......
api/config/settings/common.py
+ 345
− 44
View file @ 13d08116
This diff is collapsed.
docs/Dockerfile
+ 1
− 1
View file @ 13d08116
FROM python:3.6
RUN apt-get update && apt-get install -y graphviz
RUN pip install sphinx livereload sphinx_rtd_theme
RUN pip install sphinx livereload sphinx_rtd_theme django-environ django
WORKDIR /app/docs
docs/admin/configuration.rst
+ 119
− 113
View file @ 13d08116
Instance configuration
======================
General configuration is achieved using two type of settings.
General configuration is achieved using two type of settings:
:ref:`environment variables <environment-variables>` and
:ref:`instance settings <instance-settings>`.
.. _environment-variables:
Environment variables
---------------------
Those are located in your ``.env`` file, which you should have created
during installation.
during installation. A full list of available variables can be seen
:ref:`below <environment-variables>`.
Options from this file are heavily commented, and usually target lower level
and technical aspects of your instance, such as database credentials.
......@@ -33,7 +38,7 @@ and technical aspects of your instance, such as database credentials.
Instance settings
-----------------
Those settings are stored in database and do not require a restart of your
These settings are stored in the database and do not require a restart of your
instance after modification. They typically relate to higher level configuration,
such your instance description, signup policy and so on.
......@@ -42,7 +47,7 @@ you have the required permissions. The URL is ``/manage/settings``, and
you will also find a link to this page in the sidebar.
If you plan to use acoustid and external imports
(e.g. with the youtube backends), you should edit the corresponding
(e.g. with the YouTube backends), you should edit the corresponding
settings in this interface.
.. note::
......@@ -58,113 +63,114 @@ settings in this interface.
Configuration reference
-----------------------
.. _setting-ACCOUNT_EMAIL_VERIFICATION_ENFORCE:
``ACCOUNT_EMAIL_VERIFICATION_ENFORCE``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Determine wether users need to verify their email address before using the service. Enabling this can be useful
to reduce spam or bots accounts, however, you'll need to configure a SMTP server so that your users can receive the
verification emails.
Note that regardless of the setting value, superusers created through the command line will never require verification.
Default: ``false``
.. _setting-EMAIL_CONFIG:
``EMAIL_CONFIG``
^^^^^^^^^^^^^^^^
Determine how emails are sent.
Default: ``consolemail://``
Possible values:
- ``consolemail://``: Output sent emails to stdout
- ``dummymail://``: Completely discard sent emails
- ``smtp://user:password@youremail.host:25``: Send emails via SMTP via youremail.host on port 25, without encryption, authenticating as user "user" with password "password"
- ``smtp+ssl://user:password@youremail.host:465``: Send emails via SMTP via youremail.host on port 465, using SSL encryption, authenticating as user "user" with password "password"
- ``smtp+tls://user:password@youremail.host:587``: Send emails via SMTP via youremail.host on port 587, using TLS encryption, authenticating as user "user" with password "password"
.. note::
If ``user`` or ``password`` contain special characters (eg.
``noreply@youremail.host`` as ``user``), be sure to urlencode them, using
for example the command:
``python3 -c 'import urllib.parse; print(urllib.parse.quote_plus("noreply@youremail.host"))'``
(returns ``noreply%40youremail.host``)
.. _setting-DEFAULT_FROM_EMAIL:
``DEFAULT_FROM_EMAIL``
^^^^^^^^^^^^^^^^^^^^^^
The email address to use to send email.
Default: ``Funkwhale <noreply@yourdomain>``
.. note::
Both the forms ``Funkwhale <noreply@yourdomain>`` and
``noreply@yourdomain`` work.
.. _setting-MUSIC_DIRECTORY_PATH:
``MUSIC_DIRECTORY_PATH``
^^^^^^^^^^^^^^^^^^^^^^^^
Default: ``None``
The path on your server where Funkwhale can import files using :ref:`in-place import
<in-place-import>`. It must be readable by the webserver and Funkwhale
api and worker processes.
On docker installations, we recommend you use the default of ``/music``
for this value. For non-docker installation, you can use any absolute path.
``/srv/funkwhale/data/music`` is a safe choice if you don't know what to use.
.. note:: This path should not include any trailing slash
.. warning::
You need to adapt your :ref:`reverse-proxy configuration<reverse-proxy-setup>` to
serve the directory pointed by ``MUSIC_DIRECTORY_PATH`` on
``/_protected/music`` URL.
.. _setting-MUSIC_DIRECTORY_SERVE_PATH:
``MUSIC_DIRECTORY_SERVE_PATH``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Default: :ref:`setting-MUSIC_DIRECTORY_PATH`
When using Docker, the value of :ref:`setting-MUSIC_DIRECTORY_PATH` in your containers
may differ from the real path on your host. Assuming you have the following directive
in your :file:`docker-compose.yml` file::
volumes:
- /srv/funkwhale/data/music:/music:ro
Then, the value of :ref:`setting-MUSIC_DIRECTORY_SERVE_PATH` should be
``/srv/funkwhale/data/music``. This must be readable by the webserver.
On non-docker setup, you don't need to configure this setting.
.. note:: This path should not include any trailing slash
.. _setting-REVERSE_PROXY_TYPE:
``REVERSE_PROXY_TYPE``
^^^^^^^^^^^^^^^^^^^^^^
Default: ``nginx``
The type of reverse-proxy behind which Funkwhale is served. Either ``apache2``
or ``nginx``. This is only used if you are using in-place import.
Pod
^^^
.. autodata:: config.settings.common.FUNKWHALE_HOSTNAME
:annotation:
.. autodata:: config.settings.common.FUNKWHALE_PROTOCOL
Database and redis
^^^^^^^^^^^^^^^^^^
.. autodata:: config.settings.common.DATABASE_URL
:annotation:
.. autodata:: config.settings.common.DB_CONN_MAX_AGE
.. autodata:: config.settings.common.CACHE_URL
:annotation:
.. autodata:: config.settings.common.CELERY_BROKER_URL
:annotation:
Accounts and registration
^^^^^^^^^^^^^^^^^^^^^^^^^
.. autodata:: config.settings.common.ACCOUNT_EMAIL_VERIFICATION_ENFORCE
:annotation:
.. autodata:: config.settings.common.USERS_INVITATION_EXPIRATION_DAYS
:annotation:
.. autodata:: config.settings.common.DISABLE_PASSWORD_VALIDATORS
:annotation:
.. autodata:: config.settings.common.ACCOUNT_USERNAME_BLACKLIST
:annotation:
.. autodata:: config.settings.common.AUTH_LDAP_ENABLED
:annotation:
Media storage and serving
^^^^^^^^^^^^^^^^^^^^^^^^^
.. autodata:: config.settings.common.MEDIA_URL
:annotation: = https://mypod.audio/media/
.. autodata:: config.settings.common.MEDIA_ROOT
:annotation: = /srv/funkwhale/data/media
.. autodata:: config.settings.common.PROXY_MEDIA
:annotation: = true
.. autodata:: config.settings.common.EXTERNAL_MEDIA_PROXY_ENABLED
.. autodata:: config.settings.common.ATTACHMENTS_UNATTACHED_PRUNE_DELAY
:annotation: = true
.. autodata:: config.settings.common.REVERSE_PROXY_TYPE
.. autodata:: config.settings.common.PROTECT_FILES_PATH
Audio acquisition
^^^^^^^^^^^^^^^^^
.. autodata:: config.settings.common.MUSIC_DIRECTORY_PATH
.. autodata:: config.settings.common.MUSIC_DIRECTORY_SERVE_PATH
S3 Storage
^^^^^^^^^^
.. autodata:: config.settings.common.AWS_QUERYSTRING_AUTH
.. autodata:: config.settings.common.AWS_QUERYSTRING_EXPIRE
.. autodata:: config.settings.common.AWS_ACCESS_KEY_ID
.. autodata:: config.settings.common.AWS_SECRET_ACCESS_KEY
.. autodata:: config.settings.common.AWS_STORAGE_BUCKET_NAME
.. autodata:: config.settings.common.AWS_S3_CUSTOM_DOMAIN
.. autodata:: config.settings.common.AWS_S3_ENDPOINT_URL
.. autodata:: config.settings.common.AWS_S3_REGION_NAME
.. autodata:: config.settings.common.AWS_LOCATION
API configuration
^^^^^^^^^^^^^^^^^
.. autodata:: config.settings.common.THROTTLING_ENABLED
.. autodata:: config.settings.common.THROTTLING_RATES
.. autodata:: config.settings.common.ADMIN_URL
.. autodata:: config.settings.common.EXTERNAL_REQUESTS_VERIFY_SSL
.. autodata:: config.settings.common.EXTERNAL_REQUESTS_TIMEOUT
Federation
^^^^^^^^^^
.. autodata:: config.settings.common.FEDERATION_OBJECT_FETCH_DELAY
.. autodata:: config.settings.common.FEDERATION_DUPLICATE_FETCH_DELAY
Metadata
^^^^^^^^
.. autodata:: config.settings.common.TAGS_MAX_BY_OBJ
.. autodata:: config.settings.common.MUSICBRAINZ_HOSTNAME
.. autodata:: config.settings.common.MUSICBRAINZ_CACHE_DURATION
Channels and podcasts
^^^^^^^^^^^^^^^^^^^^^
.. autodata:: config.settings.common.PODCASTS_RSS_FEED_REFRESH_DELAY
.. autodata:: config.settings.common.PODCASTS_RSS_FEED_MAX_ITEMS
.. autodata:: config.settings.common.PODCASTS_THIRD_PARTY_VISIBILITY
Subsonic
^^^^^^^^
.. autodata:: config.settings.common.SUBSONIC_DEFAULT_TRANSCODING_FORMAT
Other settings
^^^^^^^^^^^^^^
.. autodata:: config.settings.common.INSTANCE_SUPPORT_MESSAGE_DELAY
.. autodata:: config.settings.common.FUNKWHALE_SUPPORT_MESSAGE_DELAY
.. autodata:: config.settings.common.MIN_DELAY_BETWEEN_DOWNLOADS_COUNT
.. autodata:: config.settings.common.MARKDOWN_EXTENSIONS
.. autodata:: config.settings.common.LINKIFIER_SUPPORTED_TLDS
User permissions
----------------
......@@ -194,7 +200,7 @@ to users at ``/api/admin/users/user/``.
Front-end settings
------------------
We offer a basic mechanism to customize the behaviour and look and feel of Funkwhale's Web UI.
We offer a basic mechanism to customize the behavior and look and feel of Funkwhale's Web UI.
To use any of the options below, you will need to create a custom JSON configuration file and serve it
on ``https://yourinstanceurl/settings.json``.
......@@ -296,7 +302,7 @@ On nginx, add the following snippet to your vhost config::
alias /srv/funkwhale/custom;
}
On apache, use the following one::
On apache, use the following::
Alias /custom /srv/funkwhale/custom
......
docs/conf.py
+ 13
− 2
View file @ 13d08116
......@@ -26,6 +26,16 @@ sys.path.insert(0, os.path.abspath("../api"))
import funkwhale_api # NOQA
FUNKWHALE_CONFIG = {
"FUNKWHALE_URL": "mypod.funkwhale",
"FUNKWHAL_PROTOCOL": "https",
"DATABASE_URL": "postgres://localhost:5432/db",
"AWS_ACCESS_KEY_ID": 'my_access_key',
"AWS_SECRET_ACCESS_KEY": 'my_secret_key',
"AWS_STORAGE_BUCKET_NAME": 'my_bucket',
}
for key, value in FUNKWHALE_CONFIG.items():
os.environ[key] = value
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
......@@ -35,8 +45,9 @@ import funkwhale_api # NOQA
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ["sphinx.ext.graphviz"]
extensions = ["sphinx.ext.graphviz", "sphinx.ext.autodoc"]
autodoc_mock_imports = ["celery", "django_auth_ldap", "ldap"]
add_module_names = False
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
......
docs/serve.py
+ 1
− 1
View file @ 13d08116
......@@ -6,5 +6,5 @@ call(["python", "-m", "sphinx", ".", "/tmp/_build"])
from livereload import Server, shell
server = Server()
server.watch(".", shell("python -m sphinx . /tmp/_build"))
server.watch("..", shell("python -m sphinx . /tmp/_build"))
server.serve(root="/tmp/_build/", liveport=35730, port=8001, host="0.0.0.0")
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment