How to override templates for Kiwi TCMS

This is the first publication in our customization series. It will show you how to override any template used by Kiwi TCMS. As an example we will override the email template that is used when registering new account. By default the email text looks like this:

    Welcome {{ user }},
    thank you for signing up for an {{ site_domain }} account!

    To activate your account, click this link:
    {{ confirm_url }} runs a custom Docker image based on kiwitcms/kiwi. For this image the confirmation email looks like this

    Welcome {{ user }},
    thank you for signing up for our Kiwi TCMS demo!

    To activate your account, click this link:
    {{ confirm_url }}

    GDPR no longer allows us to automatically subscribe you to
    our newsletter. If you wish to keep in touch and receive emails
    with news and updates around Kiwi TCMS please subscribe at:

    Happy testing!
    The Kiwi TCMS team

The file that we want to override is tcms/templates/email/confirm_registration.txt.

Create a local directory (git repository) which will hold customization configuration and create a file named templates.d/email/confirm_registration.txt with your text!

Next you want to make this file available inside your docker image so your Dockerfile should look like this:

    FROM kiwitcms/kiwi

    COPY ./templates.d/ /venv/lib64/python3.6/site-packages/tcms/overridden_templates/
    COPY /venv/lib64/python3.6/site-packages/tcms/settings/

where contains

    import os
    from django.conf import settings

    settings.TEMPLATES[0]['DIRS'].insert(0, os.path.join(settings.TCMS_ROOT_PATH, 'overridden_templates'))

The following code states instruct Django to look into overridden_templates first and use any templates it finds there; also make my files available in that specific location inside the docker image.

This approach can be used for all templates that you wish to override. Take into account that file names must match (Django searches templates by directory path). Now build your customized Docker image and use that for deployment!

Happy testing!

How to backup Docker volumes for Kiwi TCMS

When you start Kiwi TCMS by running docker-compose up (see here) it will automatically create 2 volumes: kiwi_db_data and kiwi_uploads. This blog post will outline how to backup these docker volumes.

Backing up the database

Kiwi TCMS is a Django application and the command provides an easy way to dump and load the database contents. To export all contents on your docker host execute:

docker exec -it kiwi_web /Kiwi/ dumpdata --all --indent 2 > database.json

This will create a file named database.json in the current directory, outside of the running container!

You can restore the database contents by using the following commands:

# delete data from all tables
docker exec -it kiwi_web /bin/bash -c '/Kiwi/ sqlflush | /Kiwi/ dbshell'
# then reload the existing data
cat database.json | docker exec -i kiwi_web /Kiwi/ loaddata --format json -

NOTE: depending on your scenario you may want to remove the existing volume (docker-compose down && docker volume rm kiwi_db_data) and re-create the DB schema (/Kiwi/ migrate) before restoring the contents!

WARNING: the above steps are applicable to Kiwi TCMS 5.1 or above. On earlier versions will fail due to various issues.

Backing up file uploads

Uploaded files can easily be backed up with:

docker exec -it kiwi_web /bin/tar -cP /var/kiwi/uploads > uploads.tar

and then restored:

cat uploads.tar | docker exec -i kiwi_web /bin/tar -x

You may also try the rsync command but be aware that it is not installed by default!

The same approach may be used to backup /var/lib/mysql/ from the kiwi_db container.


By default both docker volumes created for Kiwi TCMS use the local driver and are available under /var/lib/docker/volumes/<volume_name> on the host running your containers. You can try backing them up from there as well.

Another alternative is to use the docker-lvm-plugin and create these volumes as LVM2 block devices. Then use lvcreate -s command to create a snapshot volume. For more information see chapter 2.3.5. Snapshot Volumes from the LVM Administrator Guide for Red Hat Enterprise Linux 7.

Happy testing!

Mid-year roadmap status report

Hello everyone, in this article I will outline the progress that the Kiwi TCMS team has made towards achieving the goals on our roadmap.

Make code easier to maintain

Status: moderate progress

Initially CodeClimate reported a "D" rating with a 1 year estimated effort. Now it is still on "D" rating with a 7 months estimated effort to bring the project back in shape. Code smells have dropped from 600+ to 418, duplications have been reduced from 600+ to 359! At the same time technical debt ratio has been decreased from 32,5% to 21,6% and little over 10000 lines of code have been removed from the source code. Checkout the stats for more info!

Use pylint and pylint-django

Status: good progress

Both pylint and pylint-django have been integrated into our CI workflow. There are even a few custom built plugins that we use. The number of issues reported is down to around 900 from 4000+ initially. The cleanup has been lead by Anton Sankov with help from Ivaylo Ivanov and myself.

Render HTML, return JSON

Status: no progress

Several views were probably modified to return pure JSON in the meantime but we've not done any targeted work to resolve this issue.

Submit forms, post JSON, GET clean URLs

Status: no progress

Same as above, not much has been done in this area.

API layer

Status: complete

After Kiwi TCMS v4.0 the server side API has been reorganized and updated to follow the model/method names used internally.

After the recent version 5.0 the client side API library has been stripped to its most basic form so that you can work directly with the responses from the server.

There is no more duplication and ambiguity in names because there isn't a lot of code left!


Status: moderate progress, dropped

All RPC methods have been documented! The rest of the internals will be documented as we go along.

No vendored JavaScript libraries

Status: moderate progress

Several JavaScript libraries have been removed but we still carry around jQuery and Handlebars.js. No work has been done to convert Kiwi TCMS to use the jQuery version provided with Django.

Less HTML templates with better organization

Status: minimal progress

There are still over 100 HTML templates in Kiwi TCMS. Some of the HTML templates have been merged together, some email templates have been refactored and marked as translatable but the majority of them have not been updated for a long time.

Modern interface with Patternfly

Status: no progress

JavaScript updates and front-end testing

Status: small progress

A number of JavaScript functions have been refactored and removed during the past few releases but there are still thousands of lines of code left to deal with.

Community efforts

Status: moderate progress

We are seeing a steady stream of new users registered on and there are several active contributors (issues, translations).

Kiwi TCMS was represented at OSCAL Tirana, DjangoCon Heidelberg and PyCon Prague! We're planning to attend HackConf and OpenFest in Sofia by the end of the year.

Happy testing!

Subscribe to our newsletter