Getting Started With the Self-Managed Connectors

This guide helps you quickly set up and run a Self-Managed Connector between a PubSub+ event broker and your vendor system. You'll learn how to configure workflows, deploy the connector using different methods, and start moving data between systems.

A workflow is the configuration that defines how data flows between a source and a target. Most connectors support bidirectional data flow, allowing you to configure workflows that move data from your vendor system to PubSub+ and from PubSub+ to your vendor system. The connector supports multiple concurrent workflows per instance, enabling you to manage various data flows simultaneously. For details about your specific connector, see its documentation.

Assuming you're using the default application.yml file provided within your download, follow one of the quick starts below to connect a PubSub+ event broker and your vendor system. The quick starts use default credentials as examples to get started. The specific workflows that are configured depend on the connector you are working with.

 

Prerequisites

To run the quick starts, you need:

• a PubSub+ event broker

• access credentials for your vendor system

Depending on your vendor system, you may need to download additional JAR files for your client and its dependencies. Place these files in the libs directory. For more information about this directory, see Adding External Libraries.

If you want to run a container, you will need a container runtime. We provide instructions for Docker and Podman.

In addition, you must update the provided samples/config/application.yml with the required values for your deployment.

Quick Start: Running the Connector as a Container

Perform the following steps to start the connector with minimal configuration in a container:

1. Create a directory called config.

2. Create an application.yml or application.properties file in the config directory containing the properties needed for your connector. For an example of an configuration file, see the samples/config directory in the archive (ZIP) file you downloaded for this connector.

3. To run the container in Docker, use the following command:

   docker run -d --name my-connector \
   -p 8090:8090 \
   -v `pwd`/libs/:/app/external/libs/:ro \
   -v `pwd`/config/:/app/external/spring/config/:ro \
   --env SOLACE_JAVA_HOST=host.docker.internal:55555 \
   --env SOLACE_CONNECTOR_SECURITY_USERS_0_NAME=healthcheck \
   --env SOLACE_CONNECTOR_SECURITY_USERS_0_PASSWORD=healthcheck \
   --healthcheck-command="curl -X GET -u healthcheck:healthcheck --fail
   localhost:8090/actuator/health" \
   solace/solace-pubsub-connector-<vendor>:<version>

   To run the container in Podman, use the following command:

   podman run -d --name my-connector \
   -p 8090:8090 \
   -v `pwd`/libs/:/app/external/libs/:ro \
   -v `pwd`/config/:/app/external/spring/config/:ro \
   --env SOLACE_JAVA_HOST=host.containers.internal:55555 \
   --env SOLACE_CONNECTOR_SECURITY_USERS_0_NAME=healthcheck \
   --env SOLACE_CONNECTOR_SECURITY_USERS_0_PASSWORD=healthcheck \
   --healthcheck-command="curl -X GET -u healthcheck:healthcheck --fail
   localhost:8090/actuator/health" \					
   solace/solace-pubsub-connector-<vendor>:<version>

Where:

• <vendor> indicates the third-party system you are connecting to

• <version> is the version of the connector you are using

These run commands do the following things:

• Expose the connector’s 8090 web port (the connector’s management endpoint) to port 8090 on the host.

• Mount the libs directory and the samples/config directory. For more information, see Configuring Volumes.

• Expose a PubSub+ event broker on the host using host.docker.internal or host.containers.internal. For more information, see Connecting to Services on the Host.

• Configure a healthcheck user and command. For more information, see Configuring a Health Check.

For information about additional container settings, see Modifying the Container Configuration.

Quick Start: Running the Connector Using the Command Line

Run:

java -jar pubsubplus-connector-<vendor>-<version>.jar --spring.config.additional-location=file:samples/config/

Where:

• <vendor> indicates the third-party system you are connecting to

• <version> is the version of the connector you downloaded

For example, the JAR file name for version 1.5.2 of the Connector for Amazon SQS is pubsubplus-connector-awssqs-1.5.2.jar.

By default, this command detects any Spring Boot configuration files you place in Spring Boot's default locations.

For more information, see Configure Locations to Find Spring Property Files.

 

Quick Start: Running the Connector Using the start.sh Script

For convenience, you can start the connector through the shell script using the following commands:

chmod 744 ./bin/start.sh
./bin/start.sh [-n NAME] [-l FOLDER] [-p PROFILE] [-c FOLDER] [-ch HOST] [-cp PORT] [-j FILE] [-cm] [-cmh HOST] [-cmp PORT] [-mh HOST] [-mp PORT] [-o OPTIONS] [-b]

If you use invalid parameters, such as in the following example:

./bin/start.sh -l dummy_folder -c dummy_folder -j dummy_file.jar

The script shows you all errors at the same time:

Connector startup failed:

Following folder doesn't exists on your filesystem:     'dummy_folder'
Following folder doesn't exists on your filesystem:     'dummy_folder'
Following file doesn't exists on your filesystem:       'dummy_file.jar'

In situations where you don't provide a parameter, the script runs with the predefined values as follows:

Parameter	Default Value	Description
-n, --name	<application>	The name of the connector instance that is configured in [spring.application.name]. This name impacts the grouping of connectors only.
-l, --libs	./libs	The directory that contains the required and optional dependency JAR files, such as Micrometer metrics export dependencies (if configured). If this option is not specified, it will use the current ./libs/ directory.
-p, --profile	Empty; no profile is used.	The profile to be used with the connector’s configuration. The configuration file named application-<profile>.yml is used. If  this option is not specified, no profile is used.
-c, --config	./ or current folder	The path to the folder containing the configuration files to be applied when the connector starts up for chosen profile. If not specified, the current directory is used.
-H, --host	127.0.0.1	Specifies the host where the connector runs.
-P, --port	8090	Specifies the port where the connector runs.
-mp, --mgmt_port	9009	Specifies the management port for back calls of the current connector from PubSub+ Connector Manager. This parameter is ignored if the -cm parameter is not provided.
-j, --jar	The name of the JAR file.	The path to the specified JAR file to start the connector. If the option is not specified, the default JAR file is used from the current directory.
-cm, --manager	<application>	Specifies Connector Manager to use the configuration storage and allows you to enable the cloud configuration for the connector. When this parameter is enabled, you can specify the -mp or --mgmt_port, -H, or --host, and -cmh with the -cmp parameters, unless you want to use the default values for those parameters. This option disables the listed parameters from being read from the configuration file. In this case, the operator must explicitly specify the parameters for the script, otherwise default values are used.
-cmh, --cm_host	127.0.0.1	Specifies the host where Connector Manager is running. This parameter is ignored if -cm is not provided.
-cmp, --cm_port	9500	Specifies the port where Connector Manager is running. This parameter is ignored if -cm is not provided.
-o, --options	No default values	Specifies the JVM options used on when the connector starts. For example, -Xms64M -Xmx1G.
-tls	N/A	Specifies to use HTTPS instead of HTTP. When this parameter is used, the configuration file must contain an additional section with the preconfigured paths for the key store and trust store files.
-s, --show	N/A	Performs a dry run (does nothing). The output prints the start CLI command and its raw output and exits. This parameter is useful to check your parameters without running the connector.
-b, --background	N/A	Runs the connector in the background. No logs are shown and the connector continues running in detached mode.
-h, --help	N/A	Prints help information and exits.

The script can provide more help information from the command line by using the -h option. For more configuration examples of starting the connector together with Connector Manager, see the examples provided in the Connector Manager archive.