[id="debezium-ui"]
= {prodname} UI

:linkattrs:
:icons: font
:toc:
:toclevels: 3
:toc-placement: macro

toc::[]

[NOTE]
====
This feature is currently in incubating state, i.e. exact semantics and behaviours etc. may change in future revisions, based on the feedback we receive.
Please let us know about your feature requests or if you encounter any problems while using the {prodname} UI.
====

The {prodname} UI allows users to set up and operate connectors more easily. For instance, a list of all connectors can be viewed along with their status, etc.  The Create Connector wizard allows the user to configure connectors, guiding and validating the property entries along the way.

== Design Considerations

The UI is implemented as a https://quarkus.io/[Quarkus]-based web application.  The backend is configured with the URL(s) of one or more Kafka Connect clusters and provides a REST interface for the frontend.  The frontend user interface uses https://reactjs.org/[ReactJS] as the primary technology, utilizing https://www.patternfly.org/v4/[Patternfly] react components and design patterns.

== Installation and Configuration


=== Configure the Debezium UI
The following table shows the environment variables for the https://quay.io/repository/debezium/debezium-ui[Debezium UI container image] and the related parameter names inside `application.properties` when running the Java application without the container.

[cols="1,2,2,2,6",options="header"]

|===
|Item |Environment variable |Parameter name in application.properties |Default value |Description

|1
|DEPLOYMENT_MODE[[DEPLOYMENT_MODE]]
|`deployment.mode`
|default
|Specifies how the Debezium UI is deployed. +
 +
For example, in some environments it might not be possible to reach the underlying backend, Kafka Connect REST interface or databases, then the link:#DEPLOYMENT_MODE[deployment mode] can be switched to match the underlying infrastructure. +
 +
`default` The default deployment mode. It uses the Debezium UI backend with the configured Kafka Connect clusters via the Kafka Connect REST interface (see link:#KAFKA_CONNECT_URIS[KAFKA_CONNECT_URIS] how they are configured). +
 +
 +
`validation.disabled` When set to validation.disabled the UI frontend will not call the backend to validate the user input nor check the availability and proper configuration of database connections. That mode is used to only generate the Debezium connector JSON configuration without the UI backend validation. +
 +
|2
|KAFKA_CONNECT_URIS[[KAFKA_CONNECT_URIS]]
|`kafka.connect.uris`
|http://connect:8083
|A comma-separated list to one or more URLs of Kafka Connect REST interfaces to specify the Kafka Connect clusters that should be managed by the Debezium UI.

|===

=== Debezium UI container image

The Debezium UI https://quay.io/repository/debezium/debezium-ui[container image] is available for running the UI.  To start the UI and connect to an existing Kafka Connect instance via Docker (where KAFKA_CONNECT_URIS supplies the comma-separated list of available URI(s)):

----
$ docker run -it --rm --name debezium-ui -p 8080:8080 -e KAFKA_CONNECT_URIS=http://connect:8083 quay.io/debezium/debezium-ui:{debezium-version}
----

The UI connects to Kafka Connect via REST, so you need to make sure that the latter is reachable, e.g. by running both components on the same Docker network.

[NOTE]
====
Currently, the UI connects to un-authenticated Kafka Connect instances.  Also, there's no authorization or authentication implemented in the UI itself yet.  Until that is the case, you should secure the components e.g. with your own proxy for authorization, if needed.
====


=== Self-contained example

A self-contained example https://github.com/debezium/debezium-examples/tree/main/ui-demo[ui-demo] is available, which is included under https://github.com/debezium/debezium-examples[debezium-examples] on Github.  The ui-demo includes a docker-compose file which brings up several sources with data as well as the UI. Please refer to the https://github.com/debezium/debezium-examples/tree/main/ui-demo[README file] for more details on running the Debezium ui-demo.

== UI Operation

=== UI Connector List
The main page of the UI displays all the registered connectors.  Some of the highlights of the main page are as follows:

* *Kafka connect cluster* can be selected via the dropdown in the header.
* Connector table shows each connector with its type (MongoDB, MySQL, Oracle, PostgreSQL, or SQL Server), connector status, and connector tasks.
* A connector row can be expanded to show more details, as shown below with the 'testPostgres' connector.  Metrics are shown in the expansion area (*Note:* this feature is still under development and not functional yet).  Connector tasks are shown, with ability to *Restart* the task if desired.
* The overflow menu at the right of each connector row provides actions which allow the user to *Pause, Resume, Restart or Delete* the connector.

image::debezium-ui-connectors-list.png[{prodname} UI connectors]

=== UI Create Connector Wizard
The user can create a connector by clicking on the *Create a connector* button on the main page.  The first two steps of the wizard are required, but the remaining steps are optional. Each step will validate the user entries and provide feedback if there are problems.  After completing steps 1 and 2 successfully, the user can proceed to the final page to review and create the connector.

==== Create Connector - Connector type (required)
Choose the type of connector in Step 1.  Currently, you can specify the following connector types: *MongoDB*, *MySQL*, *Oracle*, *PostgreSQL* and *SQL Server*.

image::debezium-ui-step1.png[{prodname} UI Create connector step1]

==== Create Connector - Properties (required)
In Step 2, you enter the basic connection properties for the selected connector and confirm that the properties validate successfully. You can also specify advanced connection properties in a separate section of this step.  After successful validation, you can proceed to the next steps (Additional properties), or click *Review and finish* in the wizard footer to bypass the additional properties and proceed directly to review.

image::debezium-ui-step2.png[{prodname} UI Create connector step2]

==== Create Connector - Additional properties (optional)
The Additional properties are optional and can be summarized as follows:

* *Filter definition* - entry of *regular expressions* which define the filters for inclusion/exclusion of the items that will be included for CDC.  The included items are displayed as the filters are entered and applied.
* *Transformations* - Enable one-at-a-time modifications to individual messages. Single message transformations (SMTs) modify records before they are sent to Apache Kafka by applying them to the {prodname} connectors. For more information about single message transformations, see xref:{link-transformations}[Transformations].
* *Topic creation* - Define default properties and groups for enabling automatic topic creation.
* *Data options* - *Snapshot* and *Mapping* properties (optional).  The defaults can be viewed and changed if desired.
* *Runtime options* - *Engine* and *Heartbeat* properties (optional).  The defaults can be viewed and changed if desired.
* *Custom properties* - Enable pass-through of additional properties that are not specified in the previous sections, such as `database.*` and `database.history.*` options. You can enter any valid property name and value.

==== Create Connector - Review
The *Review* step provides a summary of the configuration that will be used to create the connector.  If you are satisfied with your selections, click *Finish* to create the connector.  To adjust any properties, navigate back to the earlier steps. You can also copy or download the JSON configuration payload for the connector.

image::debezium-ui-review-step.png[{prodname} UI Create connector review]
