Copyright © tagtog Sp. z o.o.

tagtog installation using Docker

The tagtog system runs as a mixture of Docker containers. This works on Linux, macOS, and Windows.



Your system must have installed:

  1. Docker
    • The recommended version is >= 18.03
    • To ensure that your docker installation works correctly and that you have the necessary rights to install and run docker images, run: docker info. Please ensure that you don’t get an error like permission denied, and rather as expected see the details of your docker installation.
  2. Docker Compose
    • The recommended version is >= 1.18
  3. IMPORTANT. The running docker host must have the vm.max_map_count setting variable to be at least greater than 262144. You can check the value by running: sysctl vm.max_map_count. If it is too low, set the value by running: sudo sysctl -q -w vm.max_map_count=262144.

  4. Bash Shell
    • Installed in practically all systems by default.
    • Clarification: any other Unix shell should work too, including for Windows the Unix-like environment Cygwin. However, only the Bash shell is officially supported.
  5. cURL
    • Installed in practically all systems by default

Machine Requirements

Your server (e.g. private one, or on AWS, Azure, or Linode) should meet the following minimum requirements:

First-time Install


./tagtog_on_premises restart latest $TAGTOG_HOME

# See more parameters in the tagtog_on_premises script


tagtog runs on https only and redirects all http requests to https. We recommend setting your http and https ports to the defaults 80 and 443 but you are free to choose other ones. See the tagtog_on_premises script.

By default, tagtog uses a SSL self-signed certificate. To use your own SSL certificate, place the following 2 files in the folder ${TAGTOG_HOME}/ssl:

Backups: How and where the data is stored

All tagtog data is stored in the folder: ${TAGTOG_HOME}/persistent_data/. We recommend that you have periodic backups to avoid data losses. There are other folders in $TAGTOG_HOME, which nature, however, is temporary; you can nonetheless back up that too.


The application supports http proxies and automatically recognizes your host variables $http_proxy and $https_proxy (either written in both all lower or all upper case).

Important: the port number must be explicitly written, regardless of whether the port is the default 80 for http or 443 for https. That is, always write something like: export HTTP_PROXY=IP:PORT.


You can manually check for new tagtog updates on this link. Then:

./tagtog_on_premises update
./tagtog_on_premises restart latest $TAGTOG_HOME

Change License

Might you have required a license change (e.g. to prolong your current installation or to increment the number of seats), you should also have received the new license details. With these, change the license of your system as follows:

./tagtog_on_premises change_license NEW_LICENSE_NAME NEW_LICENSE_KEY


Upon a problem, try one of the following solutions first.

If your issue or question is not resolved yet, shoot us an email: We are also happy to open a slack chat team with you for faster communication.

Please provide detailed information of the problem and send us always the container logs: docker logs tagtog_webapp_1 && docker logs tagtog_taskmanager_1.

Conflicts with ports ( bind: address already in use …)

By default, tagtog runs and exposes http on the port 80, and https on the port 443. You can change these in two ways:

  1. Set the special environmental variables:
export TAGTOG_HTTP_PORT=9080 # For example
export TAGTOG_HTTPS_PORT=9443 # For example
  1. Pass the ports parameters into the tagtog running script:
./tagtog_on_premises restart latest $TAGTOG_HOME 9080 9443

Issues with document uploading, or with the docker container tagtog_taskmanager_1:


  1. Removing all queued documents for parsing: rm "$TAGTOG_HOME/tmp/to_process/*"
  2. Restarting the application: ./tagtog_on_premises restart latest $TAGTOG_HOME

Issues in an update


./tagtog_on_premises update
./tagtog_on_premises restart latest $TAGTOG_HOME

Wrong entity offsets on the display

On a few rare cases, the entity offsets from the underlying data model (ann.json) may not match those of the interface. This visually results in some seemingly-broken entities. You might try to fix these errors running the following script:

./tagtog_on_premises fix_documents latest $TAGTOG_HOME

Lack of writing file access

On some rare cases, the docker containers cannot hold writing access to the $TAGTOG_HOME folder and file hierarchy.

In this case, figure out why that could be the case. Anything related to your user not having enough rights?

Otherwise, a quick solution is:

  1. Grant all permissions to everybody: chmod 777 -r $TAGTOG_HOME
  2. Restart the application: ./tagtog_on_premises restart ...

ml0 tagtog service taking 100% of CPU

Currently, in some cases On-Premises ML can consume too much CPU. You can verify that it’s indeed the ml service (ml0) the one overloading the CPU by checking docker stats, and looking for the tagtog_ml0_1 container.

We are working on a stable fix. For now, you can quickly liberate the resources by restarting the ml0 service only (not the entire tagtog app):

# export TAGTOG_HOME=...
docker-compose -f docker-compose.override.yaml --project-name tagtog restart ml0

Note: you can add this to a crontab file to run this every 24 or 12 hours, for example. In this case, better write an absolute path to: docker-compose.override.yaml.

tagtog docker images not found, on a new server installation

Chances are that you must re-do a first-time installation on your new server/instance, like this:

./tagtog_on_premises first_installation LICENSE_NAME LICENSE_KEY

Do the above if you encounter something like this:

Creating network "tagtog_default" with the default driver
Pulling db (tagtog_db:3.2018-W21.0)...
ERROR: The image for the service you're trying to recreate has been removed. If you continue, volume data could be lost. Consider backing up your data before continuing.

Continue with the new image? [yN]y
Pulling db (tagtog_db:3.2018-W21.0)...
ERROR: pull access denied for tagtog_db, repository does not exist or may require 'docker login'
.............................One process could not be started. Check the logs of 'tagtog_jobmanager_1'

The TAGTOG variables are not available when running as sudo

You NEED NOT to run tagtog as the root user. Actually, we recommend against this.

If for any reason, however, you do want to run as sudo, you might also need to expose your user environment variables to the root user with the -E parameter, as follows:

sudo -E ./tagtog_on_premises restart ...