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

When the customer uses Wordpress (Nice version >= v3.7), add the following dns records:

${INSTALLATION}.wp.tocco.ch

IN CNAME

wp1.{prod/stage}.tocco.ch

web.${INSTALLATION}.tocco.ch

IN CNAME

${INSTALLATION}.wp.tocco.ch

tocco.web.${INSTALLATION}.tocco.ch

IN CNAME

${INSTALLATION}.tocco.ch

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

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.

Update your Ansible Repository clone:

cd ${PATH_TO_ANSIBLE_REPOSITORY}/tocco     # Note the `/tocco`
git pull --rebase

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)
      env: !merge                                   # <-- Allow the wordpress installation as
        nice2.web.allowedRequestOrigins:            #     request origin in order for the wordpress
        - https://web.${INSTALLATION}.tocco.ch      #     plugin to work.
      routes:                                       #
        web.${INSTALLATION}.tocco.ch:               # <-- Create routes for the wordpress installation
          create_ingress: false                     #     but don't issue a letsencrypt certificate
        tocco.web.${INSTALLATION}.tocco.ch:         #

    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
test	db_server: db5.stage.tocco.cust.vshn.net
testold/testnew	db_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.

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