csspin_ce.ce_services

The csspin_ce.ce_services plugin provides a way to start and stop services required by CONTACT Elements instances by using the ce_services command-line tool.

The plugin also provisions the necessary tools to run the services, like traefik, Apache Solr, and others.

How to setup the `csspin_ce.ce_services` plugin?

For using the csspin_ce.ce_services plugin, a project’s spinfile.yaml must at least contain the following configuration.

Minimal configuration of spinfile.yaml for csspin_ce.ce_services

plugin_packages:
    - csspin-ce
    - csspin-frontend
    - csspin-java
    - csspin-python
plugins:
    - csspin_ce.ce_services
contact_elements:
    umbrella: <The umbrella to use>
python:
    version: '3.11.9'
    index_url: <package server index url to retrieve CE wheels from>
node:
    version: '18.17.1'
java:
    version: '17'

The provisioning of the required tools and the plugins dependencies can be done via the well-known spin provision-command.

How to start the services for a local CE instance?

To start the services required to run a local CE instance, the spin ce-services start command can be used. The command will start the services required by the instance specified in the spinfile.yaml.

Start

spin ce-services -i <path to instance>

How to configure services and their options?

Since the csspin_ce.ce_services plugin is based on the ce_services tool, the configuration of the services and their options is done via the setup.cfg or pyproject.toml file of the project. For more information about the configuration of the services, please refer to ce_services.

SSL/TLS support

Some use cases require accessing the CONTACT Elements instances via TLS/SSL. To enable this feature, an instance must be built with the --sslca option pointing to a valid TLS certificate file. This can be achieved by running the mkinstance task with enabled mkinstance.tls.enabled. This automatically generates a new certificate and key and sets --sslca accordingly.

To now run the services with TLS/SSL enabled, ce_services.traefik.tls.enabled must be set, ce_services.traefik.tls.cert and ce_services.traefik.tls.cert_key pointing per default to the certificate and key file generated during the mkinstance task execution. The services can be started as usual.

Sample spinfile.yaml for starting services with enabled SSL/TLS

...
ce_services:
    traefik:
        tls:
            enabled: true
mkinstance:
    tls:
        enabled: true

How to use the HiveMQ service and CE Elements integration?

The hivemq service as well as the CONTACT Elements HiveMQ integration can be used by enabling it within the configuration of ce_services. While HiveMQ can be provisioned using spin provision, the CONTACT Elements HiveMQ integration must be installed manually, e.g. by downloading it from the customer portal.

Enable HiveMQ service within spinfile.yaml

ce_services:
    hivemq:
        enabled: true
        elements_integration:
            install_dir: <path to CONTACT Elements HiveMQ integration installation directory>

(Re-) provision may be required to apply the changes.

How to enable the InfluxDB service?

The influxdb service can be enabled by setting the enabled property to true within the configuration of ce_services.

Enable InfluxDB service within spinfile.yaml

ce_services:
    influxdb:
        enabled: true

(Re-) provision may be required to apply the changes.

How to pass additional options and flags to the ce_services?

Except for the -i / --instance option, a additional flags and options passed to the ce_services task are passed to the ce_services command-line tool as shown below:

Pass additional flags and options to ce_services

spin ce-services -i <path to instance> --<flag> <value>

How to configure and use the RabbitMQ service?

The RabbitMQ service can be provisioned by enabling it in the spinfile.yaml as follows:

spinfile.yaml with enabled RabbitMQ service

ce_services:
    rabbitmq:
        enabled: true

When provisioning a project with RabbitMQ enabled, the plugin will download and install rabbitmq-server on Windows, and if executed on Linux, additionally installing and compiling the Erlang OTP. Both can be further configured via the ce_services.rabbitmq subtree.

The service can be started, e.g. via spin ce-services or manually via spin run rabbitmq-server.

How to configure and use Apache Tika?

The service Apache Tika will be provisioned automatically for contact_elements.umbrella>="2026.2". The ce_services plugin will then download the tika-server-standard.jar file for the chosen version. The downloaded .jar file will be available via the environment variable TIKA_PATH. Thus, to run the service the command spin run java -jar $TIKA_PATH can be used.

Recommendations

Caching and limiting downloads

The ce_services plugin can provision lots of additional software from various sources. To avoid unnecessary downloads and installations, it is recommended to only enable the services that are really needed.

Even though the plugin caches downloaded data, which speeds up the provisioning process on subsequent runs, in CI setups or containerized environments, this cache might not be available. Additionally, some software providers restrict and limit the number or volume of downloads.

One of such software provider is the Apache Software Foundation, which provides many of the services used by ce_services e.g. Apache Solr, Apache Tika, etc. To avoid unnecessary downloads, installations, and potential blocking by the provider, it is recommended to proactively implement counter measures, e.g.:

Set up a caching proxy for the downloads from used Apache services. Many plugins provide a mirrors property that can be used to point to such a proxy.
Pre-provision the required software in target environments, e.g. container images or directly on host systems. The ce_services can then pick them up from the location specified in the install_dir property of the respective service.

References

https://infra.apache.org/abc/

`csspin_ce.ce_services` schema reference

ce_services: 'object'

The ce_services plugin equips csspin with the ability to provision, start, stop or even control services. These services are e.g. traefik, solr, redis and many more.

ce_services.hivemq: 'object'

Configuration regarding the HiveMQ service

ce_services.hivemq.enabled: 'bool'

If enabled, the hivemq service will be started.

ce_services.hivemq.version: 'str'

The version of HiveMQ to use.

ce_services.hivemq.install_dir: 'path'

The installation directory of hivemq.

ce_services.hivemq.elements_integration: 'object'

Configuration regarding the CONTACT Elements Integration for HiveMQ

ce_services.hivemq.elements_integration.user: 'str'

The default user to use when accessing the CONTACT Elements Integration

ce_services.hivemq.elements_integration.password: 'secret'

The password corresponding to the user

ce_services.hivemq.elements_integration.install_dir: 'path'

The installation directory of the HiveMQ CONTACT Elements integration.

ce_services.influxdb: 'object'

Configuration regarding the influxdb service.

ce_services.influxdb.enabled: 'bool'

If enabled, the influxdb service will be started.

ce_services.influxdb.version: 'str'

The version of InfluxDB to use.

ce_services.influxdb.install_dir: 'path'

Installation directory of influxdb.

ce_services.traefik: 'object'

Configuration regarding the traefik service.

ce_services.traefik.version: 'str'

The version of Traefik to use.

ce_services.traefik.dashboard_port: 'str'

The port at which the Traefik dashboard should be exposed.

ce_services.traefik.install_dir: 'path'

Traefik’s installation directory.

ce_services.traefik.tls: 'object'

Configuration regarding the SSL/TLS configuration for the traefik service.

ce_services.traefik.tls.enabled: 'bool'

If set to True, the traefik service will be started with enabled SSL/TLS termination. This setting requires mkinstance.tls.cert_key and mkinstance.tls.cert to be set. Additionally, the instance must be built while mkinstance.tls.enabled is set to True.

ce_services.solr: 'object'

Configuration regarding the Apache Solr service.

ce_services.solr.version: 'str'

The version of Apache Solr to use.

ce_services.solr.install_dir: 'path'

The installation directory of Apache Solr.

ce_services.solr.version_postfix: 'str'

The Solr version postfix.

ce_services.solr.use: 'path'

The use property can be used to specify an alternative Apache Solr source to use. This is useful to rather use the system Apache Solr than the one defined in spinfile.yaml or ce_services.solr.install_dir.

ce_services.solr.mirrors: 'list'

List of mirrors to use when downloading Apache Solr

ce_services.rabbitmq: 'object'

Configuration regarding the RabbitMQ service.

ce_services.rabbitmq.version: 'str'

The version of RabbitMQ to use.

ce_services.rabbitmq.install_dir: 'path'

The installation directory of RabbitMQ.

ce_services.rabbitmq.erlang: 'object'

Configuration regarding the Erlang service.

ce_services.rabbitmq.erlang.version: 'str'

The version of Erlang to use.

ce_services.rabbitmq.erlang.install_dir: 'path'

The installation directory of Erlang.

ce_services.rabbitmq.enabled: 'bool'

ce_services.redis: 'object'

Configuration regarding redis

ce_services.redis.version: 'str'

The redis version to use.

ce_services.redis.install_dir: 'path'

The installation directory of redis.

ce_services.tika: 'object'

Configuration regarding apache tika

ce_services.tika.version: 'str'

The apache tika version to use.

ce_services.tika.install_dir: 'path'

The directory to put the tika-server.jar files.

ce_services.tika.mirrors: 'list'

List of mirrors to use when downloading Apache Tika

ce_services.loglevel: 'str'

The loglevel for the started services.

ce_services.schema: 'object'

ce_services.requires: 'object'

ce_services.requires.spin: 'list'

ce_services.requires.python: 'list'

ce_services._requires: 'list'