This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.

Create new Customer or Installation

Add DNS Entry

Usually, during initial setup, installations are only made availiable at https//${INSTALLATION} for which a DNS record can be added as described in ${INSTALLATION_NAME}

When creating a test system, also create dns records for these domains [2]:


Should you need an additional, records, have a look at DNS.

Create OpenShift Project, S3 Bucket and Database


If you haven’t setup Ansible yet, now is time to follow the instructions in Setup Ansible and read through Ansible: Usage.

  1. Update your Ansible Repository clone:

    cd ${PATH_TO_ANSIBLE_REPOSITORY}/tocco     # Note the `/tocco`
    git pull --rebase
  2. Add customer/installation to tocco/config.yml

    # ...
    abc:                                                # <-- customer
      mail_sender_default:               # <-- fallback mail address
      mail_sender_noreply:            # <-- fallback noreply address
      mail_domains:                                     # <-- domains allowed as email sender address
        abc:                                            # <-- production installation
          branch: releases/1.0
          mail_allowed_recipients_enabled: true         # <-- disable outgoing mails except for those listed
                                                        #     in mail_allowed_recipients (usually enabled
                                                        #     while installation is in pilot phase)
        abctest:                                        # <-- test installation
          branch: releases/1.0
    # ...

    In case DKIM/SPF has not been configured yet, omit the mail_sender_default, mail_sender_noreply and mail_domains settings. A default, fallback domain is used in that case. See Default Domain

    Just as shown in the example above, use these servers:








    db_server: copy from test
    solr_server: copy from test


    Naming conventions:

    Customer name

    • May only contain lower-case letters a-z and digits 0-9 and hyphens (-).

    • Customer names may not contain the substring “test”.

    Installation name

    • May only contain lower-case letters a-z, digits 0-9 and hyphens (-).

    • All installation names should start with with the customer name. Customer systems must.

    • The production system must have the same name as the customer itself. [1] By extension, the substring “test” is banned from appearing.

    • The primary test system must be called {{ customer_name }}test.

    • Test systems created during migration are called {{ customer_name }}testold and {{ customer_name }}testnew.

    • All further test systems should contain the substring “test”.


    More details about Ansible is available in Ansible: Usage

    Should you need more routes, see Add Route / Endpoint.

  3. Run Ansible Playbook

    Run playbook for installation abc and abctest:

    cd ${GIT_ROOT}/tocco
    ansible-playbook playbook.yml --skip-tags monitoring -l abc,abctest

    Or run it for all installations belonging to customer abc:

    cd ${GIT_ROOT}/tocco
    ansible-playbook playbook.yml --skip-tags monitoring -l customer_abc


Ansible as shipped by many distribution is currently suffering from an incompatibility with our S3-compatible storage:

Failed to get bucket tags: An error occurred (NoSuchTagSetError) when calling the GetBucketTagging operation: Unknown

Should you see this error, it’s easiest to patch Ansible locally to work around the issue. You have to find locally and patch it as shown in this pull request. The file is likely somewhere in /usr:

find /usr -name


When setting up the primary test system, “${CUSTOMER_NAME}test”, be sure to run the playbook for the production system too. This because, once the test system is configured, Ansible will reconfigure the production system to reuse the Docker image used by the test system.

Update and Verify Installation Entry in BO

  • update status

  • set server

Add Customer Module

Add Customer Module

(This is done only now as one cannot start an installation localy without running Ansible first. It creates the S3 bucket used locally too.)


Once all required changes have been merged, the installation can be deployed.

See Deliver (Simple)

Enable Monitoring


Only set up monitoring once the installation is online.

ansible-playbook playbook.yml -t monitoring -l customer_abc