Docker
======

Instead of installing Turkle and dependencies directly, you can run
Turkle as a Docker container, using the admin UI or scripts to manage
Projects and Batches of Tasks.

This repo comes with two Dockerfiles.  The file ``Dockerfile-sqlite``
uses SQLite as the database backend.  The file ``Dockerfile-MySQL`` uses
MySQL as the database backend.  The Turkle images created by both
Dockerfiles:

- listen for HTTP connections on port 8080
- use gunicorn as the WSGI HTTP server
- use Whitenoise to serve static files

Prebuilt Docker images
------------------------
With each release of Turkle, Docker images are uploaded to Docker Hub
and can be pulled down like this::

    docker pull hltcoe/turkle:latest

The above command line pulls the latest image.
A full list of versions is available on `Docker Hub`_.

Build SQLite Docker image
-------------------------
You can build the SQLite Turkle image using::

    docker build --force-rm -t hltcoe/turkle -f docker/Dockerfile-sqlite .

To launch a Turkle container that maps container port 8080 to Docker
host port 18080, use::

     docker run -d --name container_name -p 18080:8080 hltcoe/turkle

MySQL Docker image
------------------
The MySQL version of Turkle requires two containers - one for Turkle,
and the other for MySQL.  This multi-container Docker application is
configured and controlled by docker-compose.

To run from the root of the repository, use the ``-f`` option::

    docker compose -f docker/docker-compose.yaml build

and to run from the docker directory::

    docker compose build

The multi-container Turkle application can be built and configured with the commands::

    docker compose build
    docker compose up -d
    docker compose run turkle python manage.py createsuperuser

You'll want to wait a few minutes for the containers to load and the turkle db
to be initialized before running ``createsuperuser``.
This will stand up a Turkle server listening on port 8080.

The database files are stored in a Docker volume named turkle_db_data.
This Docker volume persists across Docker container restarts.

To upgrade to a newer version of Turkle, shut down the application
using::

    docker compose stop

Then build the newest version of the Turkle MySQL Docker image and
restart the application::

    docker compose build
    docker compose up -d

Any database migrations for the upgraded version of Turkle will be
automatically applied when the application is brought back up.

If you'd like to run the MySQL docker image on its own, look at the
environment variables set in the docker compose configuration file.

Changing the admin password
---------------------------
The SQLite Docker container has a super-user named ``admin`` with a
default password of ``admin``.  For the MySQL Docker container, the
super-user username and password are set by one of the
``docker compose`` commands listed above.

You should change the default admin password for the SQLite Docker
container by:

- connecting to the exposed container port with a web browser (e.g. connecting to http://localhost:18080/)
- logging in with username ``admin`` and password ``admin``
- clicking on the ``Admin`` link on the top left of the screen
- clicking on the ``CHANGE PASSWORD`` link at the top right of the screen
- filling out and submitting the Change Password form

Changing the number of threads, workers and worker connections
--------------------------------------------------------------
If you want to change the number of workers, threads or the connections that a worker
accepts, you can pass environment variables to the container:

- WORKERS - The number of gunicorn workers that are started (Default: 1)
- THREADS - The number of threads started by gunicorn (Default 1)
- CONNECTIONS - The maximum number of simultaneous clients (Default: 1000)

Example::
  docker run -d -e WORKERS=3 -e THREADS=4 -e CONNECTIONS=2000 -p 8080:8080 hltcoe/turkle

Logging
------------------
The gunicorn and Turkle application logs are sent to the console and are
available using `docker logs`.

Running Dockerized Turkle with a URL prefix
-------------------------------------------
If you want to reverse proxy the Turkle container so that Turkle is not available
at the root of the web server, you need to pass an environment to the container.

If this is your reverse proxy configuration for Apache::

    <Location "/annotate">
        ProxyPass http://localhost:8080
        ProxyPassReverse http://localhost:8080
    </Location>

Then run the docker container::

    docker run -d --name [container_name] -p 8080:8080 -e TURKLE_PREFIX='annotate' hltcoe/turkle

This passes the URL prefix to the Turkle application through an environment variable.

Note that after you specify the prefix as an environment variable, you will not be able to
hit the Docker-served application directly from a web browser, but only through the reverse proxy.

Customizing the settings of Docker image
------------------------------------------
If you want to change the default settings of the Docker image for your application,
the best way to accomplish that is to build a custom Docker image that depends on turkle.
Create a Dockerfile that looks like this::

    FROM hltcoe/turkle:[version]
    COPY local_settings.py /opt/turkle/turkle_site/local_settings.py

In the `local_setting.py` file, add the settings that you want to override.
As an example, to increase the maximum template size allowed by Turkle::

    TURKLE_TEMPLATE_LIMIT = 1024

To confirm that the setting has been overridden, run the new docker image, connect to the container
with a bash shell and then use the Django shell to check the setting::

   python manage.py shell
   from django.conf import settings
   print(settings.TURKLE_TEMPLATE_LIMIT)

.. _`Docker Hub`: https://hub.docker.com/r/hltcoe/turkle/tags