= Documentation for System Administrators
:!toc:
:stylesheet: ../static/css/custom.css
:icons: font
:stem: latexmath
:last-update-label!:
:favicon: static/img/ddl_favicon_black.svg

== Getting Started

DDM is a web application that builds on https://www.djangoproject.com/[Django], a Python web framework.
Therefore, to run DDM you first need to install Python (3.8 or newer) and Django 3.2.

For the installation of Python, please go to the official Python website: https://www.python.org/[python.org]

The installation of Django is described in the next section. If you are planning
to install DDM for production use, we advise to follow a comprehensive tutorial
such as the one provided by https://www.digitalocean.com/community/tutorials/how-to-set-up-django-with-postgres-nginx-and-gunicorn-on-ubuntu-22-04[Digital Ocean].


=== Install Django

To install Django and DDM, we strongly advise to use a new virtual environment (venv) for the installation.
To create a new venv, run the following command in the folder where you want your installation to be located
(the commands listed here should work for Linux and macOS; for other setups see https://www.w3schools.com/django/django_create_virtual_environment.php[here]).

[source]
----
ProjectPath> python -m venv /path/to/venv
----

Then you can activate the environment as follows:

[source]
----
ProjectPath> source /path/to/venv/bin/activate
(venv) ProjectPath>
----

Next, install Django in your virtual environment:
[source]
----
(venv) ProjectPath> pip install Django==3.2.*
----

Now that Django is installed, start a new project and access it:
[source]
----
(venv) ProjectPath> django-admin startproject yourproject
(venv) ProjectPath> cd yourproject
----
This will create a new folder `yourproject` that contains a file called `manage.py`
and a folder that is also called `yourproject`. In this subfolder you will find, among others,
the `settings.py` and the `urls.py` file.

Next, create a superuser account with your Django project:
[source]
----
(venv) ProjectPath/yourproject> python manage.py createsuperuser
----
You will be asked to provide a username and a password.

To see whether the installation of Django worked run the following command and
see whether the base site loads:
[source]
----
(venv) ProjectPath/yourproject> python manage.py runserver
----


=== Install DDM

Install the Django DDM package:

[source]
----
(venv) ProjectPath/yourproject> pip install django-ddm
----

Next, you will have to adjust several sections of your `settings.py` and `urls.py` files.

==== Update Settings.py

First, add the necessary entries to INSTALLED_APPS in your settings.py:

[source, python]
----
# settings.py

INSTALLED_APPS = [
    # ...,
    'ddm',
    'ckeditor',
    'ckeditor_uploader',
    'webpack_loader',
    'rest_framework',
    'rest_framework.authtoken',
]
----


Add the following configuration for webpack-loader to your settings.py:

[source, python]
----
# settings.py

WEBPACK_LOADER = {
    'DEFAULT': {
        'CACHE': True,
        'BUNDLE_DIR_NAME': 'ddm/vue/',
        'STATS_FILE': os.path.join(STATIC_ROOT, 'ddm/vue/webpack-stats.json'),
        'POLL_INTERVAL': 0.1,
        'IGNORE': [r'.+\.hot-update.js', r'.+\.map'],
    }
}
----

Add the DDM context processor to your template context processors.
This will enable the version indicator of the currently used DDM distribution
below the header in the admin interface.

[source, python]
----
# settings.py

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': ['templates'],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                # ...
                'ddm.context_processors.add_ddm_version'  # Add this.
            ],
        },
    },
]
----


Configure CKEditor settings in your settings.py to allow your users to upload
images and gifs in instructions and question texts:

[source, python]
----
# settings.py

CKEDITOR_RESTRICT_BY_USER = True  # Files uploaded by one user can only be accessed by this particular user
CKEDITOR_UPLOAD_PATH = 'uploads/'
----

Add time zone support to your settings.py:

[source, python]
----
# settings.py

USE_TZ = True
----

Optionally, an e-mail address restriction can be defined in settings.py. Only users whose e-mail address matches the defined regex pattern will be allowed to set up data donation projects:

[source, python]
----
# settings.py

DDM_SETTINGS = {
    'EMAIL_PERMISSION_CHECK':  r'.*(\.|@)somedomain\.com$',
},
----


==== Update urls.py

Include the DDM urls in your projects urls.py:

[source, python]
----
# urls.py

urlpatterns = [
    # ...
    path('ddm/', include('ddm.urls')),
]
----

Configure login and logout endpoints for DDM in urls.py:

[source, python]
----
# urls.py

urlpatterns = [
    ...
    path('ddm/', include('ddm.urls')),
    path('login/', auth_views.LoginView.as_view(template_name='ddm/admin/auth/login.html'), name='ddm-login'),  # You can choose whatever path and template you like
    path('logout/', auth_views.LogoutView.as_view(), name='ddm-logout'),  # You can choose whatever path and template you like
]
----

[CAUTION]
====
If you use DDM on a Django site together with https://wagtail.org/[wagtail] and you
have internationalization enabled for your wagtail urls, we recommend to use the
`prefix_default_language=False` for the i18n_patterns:

[source, python]
----
# urls.py

urlpatterns += i18n_patterns(
    path('', include(wagtail_urls)),
    prefix_default_language=False
)
----

Not doing this will cause ddm.tests.test_apis.test_participant_deletion_with_regular_login to fail.
In practice, the participant API still seems to work properly despite the test failing, however,
unexpected behaviour cannot be ruled out at this point. This will be fixed in a future version.
====

Furthermore, add the following to your urls.py:

[source, python]
----
# urls.py

urlpatterns = [
    ...
    path('ckeditor/', include('ckeditor_uploader.urls')),
]
----

DDM uses a custom CKEditor toolbar for instruction and question text definitions
that can optionally be customized (xref:topics/customize_ckeditor_configs.adoc[find out more])


==== Apply Database Migrations

The Python installation includes SQLite which is configured to be used as a database
backend in the standard `settings.py` created by Django.
For a development environment, this SQLite is totally fine, however for a production
deployment you should consider configuring a more robust and efficient database such as
PostgreSQL or MariaDB (see the https://docs.djangoproject.com/en/3.2/topics/install/#get-your-database-running[Django Documentation] for further information).

Once you have configured a database, run `python manage.py migrate` to create the ddm models in your database.


==== Test Installation
To test if your installation was successful, run `python manage.py test ddm`.
Next, run `python manage.py runserver` to start the server locally.
Visit http://127.0.0.1:8000/admin to ensure that the Data Donation Module is listed
as a subsection in the administration interface.

Visit http://127.0.0.1:8000/ddm/projects to see whether you can access the ddm
project overview site and try to create a new project.


== Optional Settings

=== Default Header Images

You can provide default images to be included in the header of the participation views.
These images will be displayed by default, but can be overwritten on a project-basis
by researchers in the project settings.

To enable default images, provide the paths to the images that you want to display
in the left and/or right part of the public header in your settings.py as follows:

[source, python]
----
# settings.py

DDM_DEFAULT_HEADER_IMG_LEFT = '/path/to/logo_left.png'
DDM_DEFAULT_HEADER_IMG_RIGHT = '/path/to/logo_right.png'
----


== Further Resources

- https://docs.djangoproject.com/en/3.2/[Official Django Documentation]
- https://www.python.org/doc/[Official Python Documentation]
- Django Tutorials on https://www.w3schools.com/django/index.php[W3Schools] or https://www.digitalocean.com/community/tutorials/how-to-install-django-and-set-up-a-development-environment-on-ubuntu-20-04[Digital Ocean]
- *xref:for_developers.adoc[Information for developers]* in this documentation
