The sections through to Extended Configuration below provide a Quick Start guide for getting a basic MyTardis installation up and running. The following section provides additional information on advanced configuration and add-on capabilities of MyTardis.



To get the most recent stable release:

git clone -b master
cd mytardis

This clones the repository as read-only.

Or, to get the current development branch:

git clone -b develop git://
cd mytardis

Quick configuration

If you want to use virtualenvwrapper, you can install it with sudo pip3 install virtualenvwrapper and set the export VIRTUALENV_PYTHON=/usr/bin/python3 in your ~/.bashrc or ~/.profile to ensure that mkvirtualenv will make a Python 3 virtual environment. For more information on configuring virtualenvwrapper, see

To activate virtualenvwrapper:

For Ubuntu 18.04 with Python 3 (using pip3 installed virtualenvwrapper):

source /usr/local/bin/

Then create the mytardis virtual environment:

mkvirtualenv mytardis

Note: the next time you want to work with this virtualenv, run the appropriate source command and then use the command: workon mytardis

Make sure you are running Python 3.x:

$ python -V
Python 3.6.9

Now upgrade pip and setup tools:

pip install -U pip setuptools

Check pip version:

$ pip -V
pip 21.0.1 from /home/ubuntu/mytardis/mytardis/lib/python3.6/site-packages/pip (python 3.6)

MyTardis dependencies are then installed with pip:

pip install -U -r requirements.txt

To install minimal Javascript dependencies for production:

npm install --production

To install Javascript dependencies for production and for testing:

npm install && npm test

To compile Webpack assets:

npm run-script build

Configuring MyTardis is done through a standard Django file. MyTardis comes with a set of default settings in its tardis/default_settings/ package. You can import this as the basis of your own config file - options defined here will override the relevant options in default_settings/*.py.

Create a new file tardis/ containing the following:

from .default_settings import *

# Add site specific changes here.

# Turn on django debug mode.
DEBUG = True

# Use the built-in SQLite database for testing.
# The database needs to be named something other than "tardis" to avoid
# a conflict with a directory of the same name.
DATABASES['default']['ENGINE'] = 'django.db.backends.sqlite3'
DATABASES['default']['NAME'] = 'tardis_db'

In addition you will need to create a new SECRET_KEY for your installation. This is important for security reasons.

A convenient method is to run the following command in your mytardis installation location:

python -c "import os; from random import choice; key_line = '%sSECRET_KEY=\"%s\"  # generated from\n' % ('from .default_settings import * \n\n' if not os.path.isfile('tardis/') else '', ''.join([choice('abcdefghijklmnopqrstuvwxyz0123456789@#%^&*(-_=+)') for i in range(50)])); f=open('tardis/', 'a+'); f.write(key_line); f.close()"

This is the minimum set of changes required to successfully run the server in development mode. You can make any other site-specific changes as necessary.


Create and configure the database:

python migrate
python createcachetable default_cache
python createcachetable celery_lock_cache

This avoids creating a superuser before the MyTardis specific UserProfile table has been created. More information about the migrate commands can be found at Configuration and Administration.

Next, create a superuser:

python createsuperuser

MyTardis can now be executed in its simplest form using:

python runserver

This will start the Django web server at http://localhost:8000/.

Running in a Docker Container

Installation steps from above can be summarised as a following Dockerfile:

FROM ubuntu:18.04

ENV DEBIAN_FRONTEND noninteractive


RUN apt-get update -y

RUN apt-get install -y \
    sudo git libldap2-dev libmagickwand-dev libsasl2-dev \
    libssl-dev libxml2-dev libxslt1-dev libmagic-dev curl gnupg \
    python3-dev python3-pip python3-venv zlib1g-dev libfreetype6-dev libjpeg-dev

RUN curl -sL | bash -
RUN apt-get install -y nodejs

RUN pip3 install virtualenvwrapper

RUN groupadd -g 1001 ubuntu
RUN useradd -rm -d /home/ubuntu -s /bin/bash -g ubuntu -G sudo -u 1001 ubuntu
USER ubuntu
WORKDIR /home/ubuntu

RUN git clone -b develop git://

ENV VIRTUAL_ENV=/home/ubuntu/mytardis/mytardis
RUN python3 -m venv $VIRTUAL_ENV

RUN pip install -U pip setuptools

WORKDIR /home/ubuntu/mytardis

RUN pip install -U -r requirements.txt
RUN npm install --production
RUN npm run-script build

RUN echo "from .default_settings import *\n\
DEBUG = True\n\
DATABASES['default']['ENGINE'] = 'django.db.backends.sqlite3'\n\
DATABASES['default']['NAME'] = 'tardis_db'\n" >> tardis/

RUN python -c "import os; from random import choice; key_line = '%sSECRET_KEY=\"%s\"\n' % ('from .default_settings import * \n\n' if not os.path.isfile('tardis/') else '', ''.join([choice('abcdefghijklmnopqrstuvwxyz0123456789@#%^&*(-_=+)') for i in range(50)])); f=open('tardis/', 'a+'); f.write(key_line); f.close()"
RUN python migrate
RUN python createcachetable default_cache
RUN python createcachetable celery_lock_cache


CMD ["python", "", "runserver", ""]

This is a minimum configuration for MyTardis, which is not suitable for running in production.

To build and run Docker container locally you will need to run following commands:

docker build . --tag mytardis
docker run --name mytardis -p 8000:8000 mytardis

Alternatively you can use pre-built Docker image from DockerHub:

docker run --name mytardis -p 8000:8000 mytardis/mytardis:develop

If you are keep in MyTardis development, we recommended you to visit for a full stack development environment, which runs using Docker.

Extended configuration

See below for some extra configuration options that are specific to MyTardis.

An automatically generated documentation of the settings can be found in tardis package.

Essential Production Settings

These settings are essential if you want to run MyTardis in production mode (DEBUG = False).


This key needs to be unique per installation and, as the name implies, be kept secret.

A new one can be conveniently generated with the command:

echo "SECRET_KEY='`python generate_secret_key`'" >> tardis/

However, the more complex command shown above needs to be used at installation time.


ALLOWED_HOSTS is a list of hostnames and/or IP addresses under which the server is accessible. If this is not set you will get a 500 Error for any request.



The database server engine that will be used to store the MyTardis metadata, possible values are postgresql_psycopg2, postgresql, mysql, sqlite3 or oracle.


The name of the database to used to store the data, this is the path to the database if you are using the SQLite storage engine.


The user name used to authenticate to the database. If you are using SQLite this field is not used.


The password used to authenticate to the database. If you are using SQLite this field is not used.


The host name of the machine hosting the database service. If this is empty then localhost will be used. If you are using SQLite then this field is ignored.


The port the database is running on. If this is empty then the default port for the database engine will be used. If you are using SQLite then this field is ignored.


For further information see LDAP authentication



The path to the default MyTardis storage location. This is where files will be stored to if you do not provide any other location explicitly through ``StorageBox``es.


If True, a Datafile requires an MD5 or SHA-512 checksum from the time it is first recorded in the MyTardis database. This enables a model-level constraint check each time a Datafile record is saved. Defaults to True. Datafile record is saved.


If True, a Datafile require a size from the time it is first recorded in the MyTardis database. This enables a model-level constraint check each time a Datafile record is saved. Defaults to True.


If True, ingestion of a Datafile is only permitted if the Datafile matches its supplied size and/or checksums. Defaults to True.

Access Rights & Licensing


By default, the Creative Commons Attribution 4.0 International licences are loaded.

You can use the admin interface to add other licences. Please ensure allows_distribution is set to the correct value to ensure the licence appears in conjunction with suitable public access types.



This contains a list of post save filters that are execute when a new data file is created.

The POST_SAVE_FILTERS variable is specified like:

    ("tardis.tardis_portal.filters.exif.EXIFFilter", ["EXIF", "http://exif.schema"]),

For further details please see the Filter Setup section.

Archive Organizations


This is a prioritized list of download archive formats to be used in contexts where only one choice is offered to the user; e.g. the “download selected” buttons. (The list allows for using different archive formats depending on the user’s platform.)


This gives the default archive “organization” to be used. Organizations are defined via the next attribute.


This is a hash that maps archive organization names to Datafile filename mapper functions. These functions are reponsible for generating the archive pathnames used for files written to “tar” and “zip” archives by the downloads module.

The DOWNLOAD_PATH_MAPPERS variable is specified like:

    'test': ('tardis.apps.example.ExampleMapper',),
    'test2': ('tardis.apps.example.ExampleMapper', {'foo': 1})

The key for each entry is the logical name for the organization, and the value is a tuple consisting of the function’s pathname and a set of optional keyword arguments to be passed to the function. At runtime, the function is called with each Datafile as a positional argument, and an additional ‘rootdir’ keyword argument. The function should compute and return a (unique) pathname based on the Datafile and associated objects. If the function returns None, this tells the archive builder to leave out the file.

By default, the archive builder uses the built-in “deep-storage” mapper which gives pathnames that try to use directory information to rebuild a file tree.

Storage Locations ( StorageBox es)

A MyTardis instance can be configured to support multiple locations ( StorageBox es) for storing data files. Each location holds copies ( DataFileObject s) of DataFile s that are recorded in the MyTardis database.

The StorageBox architecture is compatible with the Django File Storage API. This makes it relatively easy to support a number of different storage backends such as cloud storage or SFTP servers. Please refer to the StorageBox documentation for more detailed information.

Additional Tabs

Additional and custom tabs may be configured in MyTardis on a per-installation basis. The tabs are implemented as separate Django applications with a single view (index), listed in the TARDIS_APPS configuration item and either linked to, or installed in the TARDIS_APP_ROOT directory, by default tardis/apps.

Documentation on the additional tabs is available from Apps and Contextual Views.

Additional Views

Custom views may be configured in MyTardis on a per-installation basis. The tabs are implemented as separate Django applications with a single view function listed in the *_VIEWS configuration item and added to the INSTALLED_APPS list.

Refer to the views documentation for further information.

Site Customisations

Some settings that allow customised messages and styles.

<p><strong>... introduction and publication agreement ...</strong></p>
SITE_STYLES = ''  # should be CSS

# if either GA setting is empty, GA is disabled
GOOGLE_ANALYTICS_ID = ''  # whatever Google provides
GOOGLE_ANALYTICS_HOST = ''  # the host registered with Google

# these refer to any template finder findable location, e.g. APPDIR/templates/...
CUSTOM_ABOUT_SECTION_TEMPLATE = 'tardis_portal/about_include.html'
CUSTOM_USER_GUIDE = 'user_guide/index.html'


Collecting Static Files

For performance reasons you should avoid static files being served via the application, and instead serve them directly through the webserver.

To collect all the static files to a single directory:

python collectstatic

This contains the location to deposit static content for serving.


The path static content will be served from. (eg. /static or

Serving with Nginx + Gunicorn

In this configuration, Nginx serves static files and proxies application requests to a Gunicorn server:

   HTTP  +-----------+       +-----------------+
+------->|   Nginx   +------>| Gunicorn Server |
         +-----------+       +-----------------+

Nginx should then be configured to send requests to the server. Here is an example configuration (SSL part from Mozilla SSL configurator). Please amend for your own needs and understand the settings before deploying it.:

upstream mytardis {
    server unix:/var/run/gunicorn/mytardis/socket;
    server backup;
server {
    listen 80 default_server;
    return 301 https://$server_name$request_uri;

server {
    listen 443 default_server ssl;

    # certs sent to the client in SERVER HELLO are concatenated in ssl_certificate
    ssl_certificate /path/to/signed_cert_plus_intermediates;
    ssl_certificate_key /path/to/private_key;
    ssl_session_timeout 5m;
    ssl_session_cache shared:SSL:50m;

    # Diffie-Hellman parameter for DHE ciphersuites, recommended 2048 bits
    ssl_dhparam /path/to/dhparam.pem;

    # intermediate configuration. tweak to your needs.
    ssl_protocols TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;

    # HSTS (ngx_http_headers_module is required) (15768000 seconds = 6 months)
    add_header Strict-Transport-Security max-age=15768000;

    # OCSP Stapling ---
    # fetch OCSP records from URL in ssl_certificate and cache them
    ssl_stapling on;
    ssl_stapling_verify on;

    ## verify chain of trust of OCSP response using Root CA and Intermediate certs
    ssl_trusted_certificate /path/to/root_CA_cert_plus_intermediates;

    resolver <IP DNS resolver>;

    client_max_body_size 4G;
    keepalive_timeout 5;

    gzip off;  # security reasons
    gzip_proxied any;
    # MyTardis generates uncompressed archives, so compress them in transit
    gzip_types application/x-javascript text/css;
    gzip_min_length 1024;
    gzip_vary on;

    location / {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;
        proxy_redirect off;
        proxy_pass http://mytardis;
        client_max_body_size 4G;
        client_body_buffer_size 8192k;
        proxy_connect_timeout 2000;
        proxy_send_timeout 2000;
        proxy_read_timeout 2000;

    location /static/ {
        expires 7d;
        alias /srv/static_files/;

The X-Forwarded-Proto header is explained in

It is recommended to pass protocol information to Gunicorn. Many web frameworks use this information to generate URLs. Without this information, the application may mistakenly generate ‘http’ URLs in ‘https’ responses, leading to mixed content warnings or broken applications.

To tell MyTardis to set this header in its HTTP requests and redirects, you’ll need the following in your


For more information, including warnings on the risks of misconfiguring this setting, see:

Don’t forget to create the static files directory and give it appropriate permissions. The location is set in the file.

# Collect static files to ``settings.STATIC_ROOT``
python collectstatic
# Allow Nginx read permissions
setfacl -R -m user:nginx:rx static_dir

Serving with Apache HTTPD + mod_wsgi

We do not support the use of Apache. If you need this and want to support this use case, we welcome your contribution of any relevant documentation.

Creating Systemd Services for Gunicorn and Celery

Gunicorn is a Python WSGI HTTP Server which is suitable for production (when combined with NGINX). Gunicorn is typically run from a Systemd service (on Ubuntu 16.04 or Ubuntu 18.04), saved in /etc/systemd/system/gunicorn.service:

Description=gunicorn daemon

ExecStart=/home/mytardis/.virtualenvs/mytardis/bin/gunicorn \
  -c -b unix:/tmp/gunicorn.socket \
  -b \
  --log-syslog \


On older systems (Ubuntu 14.04), Supervisor can be used instead of Systemd. In this case, the Gunicorn service would be configured in /etc/supervisor/conf.d/gunicorn.conf:

 -c /home/mytardis/mytardis/
 -b unix:/tmp/gunicorn.socket

A single server MyTardis deployment requires only one Gunicorn service, but MyTardis can be installed on multiple web nodes, each running NGINX and Gunicorn to accomodate load balancing and high availability using HAProxy.

The Celery workers which run MyTardis asynchronous tasks also require a service configuration, which is typically implemented with Systemd (on Ubuntu 16.04 or Ubuntu 18.04), saved in /etc/systemd/system/celeryworker.service:

Description=celeryworker daemon

ExecStart=/home/mytardis/.virtualenvs/mytardis/bin/celery worker \
  -A tardis.celery.tardis_app \
  -c 2 -Q celery,default -n "allqueues.%%h"


On older systems (Ubuntu 14.04), Supervisor can be used instead of Systemd. In this case, the Celery worker service would be configured in /etc/supervisor/conf.d/celeryworker.conf:

command=/home/mytardis/.virtualenvs/mytardis/bin/celery worker
  -A tardis.celery.tardis_app
  -c 2 -Q celery,default -n "allqueues.%%h"

For tasks scheduled by Celerybeat, the Systemd service configuration (for Ubuntu 16.04 or Ubuntu 18.04), is saved in /etc/systemd/system/celerybeat.service:

Description=celerybeat daemon

ExecStart=/home/mytardis/.virtualenvs/mytardis/bin/celery beat \
  -A tardis.celery.tardis_app --loglevel INFO


On older systems (Ubuntu 14.04), Supervisor can be used instead of Systemd. In this case, the Celerybeat service would be configured in /etc/supervisor/conf.d/celerybeat.conf:

command=/home/mytardis/.virtualenvs/mytardis/bin/celery beat
  -A tardis.celery.tardis_app --loglevel INFO