Components

Introduction

Some components - or more concrete: pods - can be turned on and off in appsuite-stack/helm/appsuite/values.yaml.

Enabling or disabling them only influences whether or not the pod will be started. Configuration in other pods is not updated to reflect the change. That configuration must be changed explicitly.

Configurations

core-cacheservice

values.yaml:   cacheService / s3ObjectStores|sproxydObjectStores / ...

If the cache service is enabled, it needs a configuration for using a S3 or Scality object storage.

core-documentconverter

The document converter tries to find a cache service per default.

values.yaml:   core-documentconverter / documentConverter / cache / remoteCache / enabled = true/false

If the cache service is used, the document converter will find it automatically.

If the cache service is disabled, the document converter should be configured to not try finding a cache service by setting the above configuration to false.

The document converter will automatically use reasonable defaults for temporary (short term) local caching if the cache service is not available.

Disable using a document converter in core-mw

The middleware will try to find a document converter per default. If you have disabled the document converter, you should also configure core-mw so it doesn't continue searching for a document converter:

core-mw:   com.openexchange.capability.document_preview: "false"

core-mw:   packages:     status:       open-xchange-documentconverter-api: disabled       open-xchange-documentconverter-client: disabled

core-imageconverter

DEPRECATED SOON - in the near future, the image converter will use the cache service instead of handling the caching itself.

For the time being, this configuration is needed so that the image converter can handle caching in an object storage:

values.yaml:   objectCache / s3ObjectStores /...   objectCache / mysql   objectCache / sproxydObjectStores/ ...

Note: objectCache type fileStore is not supported and will vanish once the cache service is used.

Disabling caching in image converter:

Just leave the following values empty, comment that values out or remove them so that objectCache.s3ObjectStores and objectCache/sproxydObjectStores get empty.

values.yaml:   objectCache / s3ObjectStores / id = -1   objectCache / sproxydObjectStores/ id = -1

Disable using an image converter in core-mw

The middleware will try to find an image converter per default. If you have disabled the image converter, you should also configure core-mw so it doesn't continue searching for an image converter:

core-mw:   packages:     status:       open-xchange-imageconverter-client: disabled

office-web

If you enable or disable office-web (OX Documents), some capabilities needs to be set in core-mw accordingly:

core-mw:   com.openexchange.capability.text: "true/false"   com.openexchange.capability.presentation: "true/false"   com.openexchange.capability.spreadsheet: "true/false"   com.openexchange.capability.document_preview: "true/false"   com.openexchange.capability.presenter: "true/false"   com.openexchange.capability.guard-docs: "true/false" (only use true if guard is enabled)

core-mw:   packages:     status:       open-xchange-documents-templates: enabled/disabled       open-xchange-documents-backend: enabled/disabled       open-xchange-documents-monitoring: enabled/disabled

core-spellcheck

The spell checker service is only used in OX Documents and is used per default.

If you disable core-spellcheck, also tell OX Documents to not search for a spell checker and to not offer spell checking to the user:

core.mw:   io.ox/office//module/spellingEnabled=false   com.openexchange.office.spellcheck.remoteURL=

wopi-server

The wopi-server is a service to edit documents with Collabora Online for which OX Documents(office and office-web) must be enabled.

Configuration

core-mw

The core-mw capability for using Collabora Online must be enabled.

core-mw:
    properties:
        com.openexchange.capability.documents_collabora: "true"
Enable the wopi-server and configure the properties
wopi-server:
  enabled: true
  properties:
OX App Suite and Collabora Online

The URLs of both services must be configured so that documents can be opened in OX App Suite using Collabora Online.

    appsuite:
      # The URL to the OX App Suite e.g. https://example.com/appsuite
      url:
    wopiclient:
      collabora:
        # The URL to the Collabora Online discovery page e.g. https://example.com/hosting/discovery
        discoveryUrl:
Redis
    redis:
      # The Redis mode must be “standalone” or “sentinel”, the default is “standalone”
      mode: "standalone"
      # List of Redis hosts in the format host:port
      hosts: []
      # The database of the Redis. The default is 0
      database: 0
      # The name of the master in the redis sentinel mode, the default is "mymaster".
      sentinelMasterId: "mymaster"

      # User name/password authentication is disabled by default.
      auth:
        enabled: false
        username: ""
        password: ""

      # The TLS/SSL connection is disabled by default.
      # Use the Java "keytool" to generate the "keystore" and the "truststore" in storetype "PKCS12".
      tls:
        enabled: false
        keystore:
        keystorePassword:
        truststore:
        truststorePassword:
Further configuration options

The values entered are the default. When “external services” are mentioned below, this refers to OX App Suite and Collabora Online.

    accesstoken:
      # The number of seconds the access token is valid in seconds.
      expirySeconds: 43200

    # The maximum file size that can be retrieved from the wopi server
    # can be written with the following (case-sensitive) post-fixes: B, KB, MB.
    maxFileSize: 100MB

    externalService:
      # The timeout for the connection to the external services in seconds.
      connectionTimeoutSeconds: 10
      # The read timeout for the external services in seconds.
      readTimeoutSeconds: 90
      # The write timeout for the external services in seconds.
      writeTimeoutSeconds: 90

booking

Appointment Polls and Appointment Booking, a subchart of the stack chart (bookingservice) since App Suite 8.53. Off by default; booking_enabled: true turns it on, and the render then takes care of what the chart leaves to the deployment:

  • the booking capability on core-mw, which the UI plugin requires to show up at all
  • a bookingdb database with its own booking user: created on our own MariaDB, and as a ready SQL file for an admin on any other server (see Database)
  • the middleware's REST basic auth, which calendar conflict checking (free/busy) uses
  • the public base URLs (https://<as_hostname>/booking/poll, /booking/book), and CORS origins for every App Suite hostname
  • outbound mail through the postfix battery, when install_postfix

The chart runs two pods by default; the service is stateless, so replicas_booking: 1 is enough where availability does not matter.

The route to /booking comes with the stack chart's Istio VirtualService, and core-ui-middleware discovers the UI plugin from the booking Service's labels, so neither needs configuring. It follows that booking needs use_istio; the render refuses otherwise.

Anything else in the chart's bookingConfig goes into booking_config, merged key by key over the defaults above:

booking_enabled: true
booking_config:
  mcp:
    enabled: true
  mail:
    host: smtp.example.com
    port: 587
    from: "Bookings <bookings@example.com>"
    authMethod: plain
    user: bookings@example.com

Mail

With install_postfix, booking sends through the postfix battery, which relays without authentication, so there is nothing to configure. It only delivers to as_hostname mailboxes, though: booking mails to an outside address go nowhere in a lab.

An external relay goes into booking_config.mail, as in the example above. With authMethod: plain it wants the relay's password, which the render cannot generate, so seed it into the vault before rendering; the render refuses until it is there, and then hands it to the chart as MAIL_PASS in values.secret.yaml:

python vault.py -c -v rendered/<name>/vault.json -s booking.mail.password='<password>'

The chart takes env as literal values only, so the password is readable in the Deployment spec.

Database

Booking keeps its data in a database of its own, bookingdb, which it reaches as the user booking. Its password is generated into the vault as booking.db.password. The service creates its tables itself (a migration Job of the chart), but the database and the user have to exist.

The booking pods reach the database at mysql_host (or mysql_write_host). They have no haproxy sidecar, which only core-mw gets, so with use_haproxy_sidecar they connect to the first of haproxy_galera_nodes directly, without the sidecar's failover. booking_db_host and booking_db_port override all of this, for an address that fails over by itself, like a load balancer in front of the cluster. The render refuses a loopback address.

Wherever mariadb-operator does the database setup, the render creates the database and the user: db0-booking does it through the operator, on every install. That is our own MariaDB (install_mariadb), and an external one with install_mariadb_operator kept on, which the operator reaches as root through an ExternalMariaDB (see examples/lab.external-db.yml). On mariadb-light, install.sh runs the statements below through pypod as root, whose password is ours.

On an external server without the operator, an admin creates them. The render writes the statements, with the password already filled in, to booking-db-init.secret.sql next to install.sh; run it once on the server as a user allowed to create databases, users and grants, before the install:

mysql -h <host> -P <port> -u <admin> -p < rendered/<name>/booking-db-init.secret.sql

It is idempotent, so it can run again, and it contains this:

SET SESSION sql_mode = CONCAT_WS(',', @@SESSION.sql_mode, 'NO_BACKSLASH_ESCAPES');
CREATE DATABASE IF NOT EXISTS `bookingdb`;
CREATE USER IF NOT EXISTS 'booking'@'%' IDENTIFIED BY '<booking.db.password>';
ALTER USER 'booking'@'%' IDENTIFIED BY '<booking.db.password>';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, INDEX, REFERENCES ON `bookingdb`.* TO 'booking'@'%';

The password comes out of the vault with python vault.py -v rendered/<name>/vault.json -q -g booking.db.password. The ALTER USER keeps the vault the source of truth: running the file again after the vault changed resets the password to match. Narrow '%' to the cluster's egress addresses if the server's policy asks for it.

Uninstalling never drops the database: the db0-* releases leave schemas, users and grants in place (cleanupPolicy: Skip), and on mariadb-light or a server set up by hand nothing is undone.