.. _configuration:
Kiwi TCMS configuration settings
================================
All sensible settings are defined in ``tcms/settings/common.py``. You will have
to update some of them for your particular production environment.
.. note::
After adjusting settings for your environment you have to configure
Kiwi TCMS via its web interface! As a minimum you have to
:ref:`configure-kiwi-domain` and :ref:`configure-bug-trackers`!
.. note::
Additional information how to override Kiwi TCMS behavior can be found at
``_!
.. literalinclude:: ../../tcms/settings/common.py
:language: python
Augmenting behavior with signal handlers
----------------------------------------
Kiwi TCMS defines signals which are triggered during specific events.
Administrators may override the default handlers and/or connect additional
ones to augment the default behavior of Kiwi TCMS. For more information
refer to :mod:`tcms.signals`.
Language and emojis
-------------------
By default our ``docker-compose.yml`` file is configured with MariaDB and
uses charset ``utf8mb4`` and collation ``utf8mb4_unicode_ci``. That should
be sufficient to support many languages plus emojis. If you are having troubles
consult `MariaDB Character Sets and Collations `_
documentation.
If you need to change the default settings see ``docker-compose.yml`` or
``/etc/mysql/conf.d/mariadb.cnf`` if using a stand alone DB server! On the
application side see ``DATABASES['default']['OPTIONS']`` in
``tcms/settings/common.py``.
Time zone settings
------------------
By default Kiwi TCMS is configured to use the ``UTC`` time zone.
``/etc/localtime`` inside the docker image also points to
``/usr/share/zoneinfo/Etc/UTC``!
The settings which control this behavior are:
- ``USE_TZ`` - controls whether or not Django uses timezone-aware
datetime objects internally. Can also be controlled via ``KIWI_USE_TZ``
environment variable
- ``TIME_ZONE`` - a string representing the time zone for this application.
This should match the actual configuration of your server/docker container!
Can also be controlled via ``KIWI_TIME_ZONE`` environment variable.
Your server/docker container clock should also match the accurate time of day!
.. important::
Unlike language there is no way to automatically receive time zone
information from the browser and display different values for users.
Instead Kiwi TCMS displays the current server time & time zone in the
navigation bar! All other timestamps are in the same time zone!
.. _email-settings:
E-mail settings
---------------
Kiwi TCMS supports email notifications which by default are sent over SMTP and
need to be configured via the following settings:
- Common settings::
SERVER_EMAIL = DEFAULT_FROM_EMAIL = 'kiwi@example.com'
# additional Kiwi TCMS setting
EMAIL_SUBJECT_PREFIX = '[Kiwi-TCMS] '
- SMTP specific settings::
EMAIL_HOST = 'smtp.example.com'
EMAIL_PORT = 25
EMAIL_HOST_USER = 'smtp_username'
EMAIL_HOST_PASSWORD = 'smtp_password'
To enable SSL or TLS support include one of the following::
EMAIL_USE_TLS = True
EMAIL_USE_SSL = True
For more details refer to Django documentation at https://docs.djangoproject.com/en/3.0/topics/email/
Testing and debugging e-mail configuration
------------------------------------------
Sending test e-mail to one or more addresses::
docker exec -it kiwi_web /Kiwi/manage.py sendtestemail user1@example1.tld user2@example2.tld ...
More details at: https://docs.djangoproject.com/en/3.0/ref/django-admin/#sendtestemail
Using Amazon SES instead of SMTP email
--------------------------------------
If you'd like to use an external email service, like Amazon SES you need
to configure the following settings too::
EMAIL_BACKEND = 'django_ses.SESBackend'
AWS_SES_ACCESS_KEY_ID = 'xxxxxxxxxxxxxxxxxxxx'
AWS_SES_SECRET_ACCESS_KEY = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY'
Also modify ``Dockerfile`` to include the following lines::
RUN pip install django_ses
.. warning::
The django-ses add-on is available as part of Kiwi TCMS Enterprise!
Kerberos authentication
-----------------------
See
`kiwitcms-auth-kerberos `_.
Anonymous read-only access
--------------------------
.. versionchanged:: 8.7
By default Kiwi TCMS requires :ref:`permissions`,
including view permissions which means users must be logged in!
If you wish to allow anonymous read-only access then define the following setting::
AUTHENTICATION_BACKENDS = [
'django.contrib.auth.backends.ModelBackend',
'guardian.backends.ObjectPermissionBackend',
'tcms.kiwi_auth.backends.AnonymousViewBackend',
]
.. versionadded:: 8.7
``tcms.kiwi_auth.backends.AnonymousViewBackend`` was added instead of the
previous ``PUBLIC_VIEWS`` setting.
.. versionchanged:: 8.8
``guardian.backends.ObjectPermissionBackend`` was added and the
``AUTHENTICATION_BACKENDS`` setting is now explicitly specified!