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}.tocco.ch for which a DNS record can be added as described in ${INSTALLATION_NAME}.tocco.ch.

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

${CUSTOMER}testnew.tocco.ch
${CUSTOMER}testold.tocco.ch

Should you need an additional, non-tocco.ch records, have a look at DNS.

Create OpenShift Project, S3 Bucket and Database

Warning

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: info@domain.ch               # <-- fallback mail address
  mail_sender_noreply: noreply@domain.ch            # <-- fallback noreply address
  mail_domains:                                     # <-- domains allowed as email sender address
    domain.ch:
    domain.net:
  installations:
    abc:                                            # <-- production installation
      branch: releases/1.0
      db_server: db7.prod.tocco.cust.vshn.net
      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
      db_server: db5.stage.tocco.cust.vshn.net
# ...

    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 tocco-mailing-service.ch.

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

    Environment

    Servers

    production
    db_server: db7.prod.tocco.cust.vshn.net
    solr_server: solr2.tocco.cust.vshn.net

    test
    db_server: db5.stage.tocco.cust.vshn.net
    solr_server: solr1.stage.tocco.cust.vshn.net

    testold/testnew
    db_server: copy from test
    solr_server: copy from test

    Important

    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”.

    Hint

    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

Hint

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 s3_bucket.py locally and patch it as shown in this pull request. The file is likely somewhere in /usr:

find /usr -name s3_bucket.py

Hint

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.)

Deploy

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

See Deliver (Simple)

Enable Monitoring

Important

Only set up monitoring once the installation is online.

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

Footnotes