Deploying a Replicator through Docker

Version availability

Available in 8.0.4 and later.

At present, the docker deployment can only be used to configure a "cluster-extractor" topology, and will therefore require that you have an operational Tungsten Cluster running that will be the source fo this deployment.

For more information on a "cluster-extractor", see "Replicating Data Out of a Cluster"

Providing you have a license to use Tungsten Clustering or Tungsten Replicator, you will be able to download the docker image from the download portal of the Continuent Website.

The image is available as a gzipped tar ball, and the following steps outline how to import and use the image.

The Docker replicator runs as a self-contained container. It:

• Waits for the destination MySQL to become reachable before starting.
• Reads its configuration from a mounted tungsten.ini file — the same INI format used elsewhere in Tungsten, no new syntax to learn.
• Persists THL and dynamic state on the host filesystem via Docker volumes, so the replicator survives container restarts and upgrades without losing position.
• Exposes standard ports — the Prometheus metrics exporter on 8091 and the REST API on 8097 — exactly as a traditionally installed replicator would.
• The container is based on eclipse-temurin:25-noble and ships everything the replicator needs, including the MySQL client binaries. No external dependencies are required on the host beyond Docker itself.

Step 1 : Download the files and load into Docker

Download the correct file for your environment architecture, for example amd64 or arm64, and then extract the tar ball, and load into docker, for example:

shell> tar xvzf tungsten-replicator-docker-${VERSION}-${ARCH}.tar.gz
shell> cd tungsten-replicator-docker-${VERSION}
shell> docker load --input tungsten-replicator-${VERSION}-${ARCH}.tar
shell> docker images

where:

• VERSION = Tungsten Replicator version with build number like 8.0.4-132
• ARCH = [amd64 | arm64 ]

Step 2 : Configure the Replicator

Before launching the replicator, you will need to apply a number of configuration changes so that the Replicaror can communicate with your cluster.

The compose.yaml file

The following changes to compose.yaml are required:

Variable	Purpose
DB_HOST	Hostname or IP of the destination MySQL instance
DB_PORT	Port of the destination MySQL (typically 3306)
container_name	Name shown in docker ps — use something meaningful like replicator-alpha
hostname	The hostname the replicator will identify itself as
extra_hosts	Optional host-to-IP mappings injected into /etc/hosts inside the container

The extra_hosts section is particularly useful when the source cluster nodes are not resolvable by DNS from inside the container. Simply uncomment and list each hostname-to-IP mapping:

extra_hosts:
- "cluster-db1:192.168.30.82"
- "cluster-db2:192.168.30.83"
- "cluster-db3:192.168.30.84"

The volumes section mounts four paths from the host into the container:

volumes:
- ./conf/tungsten.ini:/etc/tungsten/tungsten.ini   # your configuration
- ./thl:/opt/continuent/thl                        # THL storage (persisted)
- ./state:/opt/continuent/tungsten/tungsten-replicator/conf/dynamic  # dynamic state
- ./security:/opt/continuent/share                 # security keystores

All four directories are created automatically by Docker Compose on first run if they do not exist yet.

The conf/tungsten.ini File

Copy the provided template and edit it:

shell> cp conf/tungsten.ini.clusterextractor conf/tungsten.ini

The template for a cluster-extractor looks like this:

[defaults]
# Set to false (or remove) to enable SSL/TLS between replicator and cluster
disable-security-controls=true

[cluster]
topology=cluster-alias
members=db1,db2,db3
master=db1

[standalone_replication]
topology=cluster-slave

relay=replicator-alpha       # Must match the container_name in compose.yaml
relay-source=cluster

replication-user=tungsten
replication-password=secret

# replication-host=localhost  # Uncomment if MySQL is on a different host
# replication-port=3306       # Uncomment to use a non-default port

log-slave-updates=true

The key settings to understand:

• [cluster] — describes the source Tungsten Cluster: its topology, the list of member nodes, and which one is currently the primary.
• [standalone_replication] — describes the local replication service. The topology=cluster-slave value is what tells the replicator it is acting as an external consumer of an existing cluster's THL stream.
• relay — must match the container_name and hostname in compose.yaml; this is the name the replicator uses to identify itself on the THL network.
• relay-source — the name of the [cluster] section to pull from.

Step 3 : Launch

shell> docker compose up -d
shell> docker ps

The container will wait up to 60 seconds for the destination MySQL to become available before starting the replication service. This means you do not need to worry about startup ordering in your environment.

Verify Replication

Connect to the running container and check replicator status:

shell> docker exec -it replicator-alpha bash
shell> trepctl status

When the replicator is healthy you will see state: ONLINE and a relativeLatency that counts up from a small number of seconds. The pipelineSource field shows which cluster node the replicator is currently pulling THL from — it will automatically fail over to another cluster member if that node becomes unavailable.

Enabling Security (TLS)

By default, the template ships with disable-security-controls=true for quick bring-up. For production deployments, you will want to enable TLS between the replicator container and the source cluster.

Step 1: Set disable-security-controls=false (or remove the line) in conf/tungsten.ini Step 2: Copy the following files from /opt/continuent/share on any live, security-enabled node of the source cluster into the security/ directory of your package:

passwords.store
tungsten_keystore.jks
tungsten_truststore.ts
tungsten_thl_keystore.jks
tungsten_thl_truststore.ts

That is all that is needed. The security/ directory is mounted into the container at /opt/continuent/share, which is where the replicator looks for its keystores.

Securing the MySQL Connection

If the destination MySQL requires encrypted client connections, a few extra steps are needed to import the MySQL TLS certificates into the Tungsten keystores.

Retrieve the following from the destination MySQL host:

ca.pem
client-cert.pem
client-key.pem

Then import them:

shell> PASSWD=tungsten   # change if your keystore password is different
shell> openssl pkcs12 -export \
-in client-cert.pem -inkey client-key.pem \
-out client.p12 -name mysql_dest \
-passout pass:$PASSWD

shell> keytool -importkeystore -noprompt \
-srckeystore client.p12 -destkeystore security/tungsten_keystore.jks \
-srcalias mysql_dest -destalias mysql_dest \
-srcstoretype pkcs12 -deststoretype JKS \
-srcstorepass $PASSWD -deststorepass $PASSWD \
-srckeypass $PASSWD -destkeypass $PASSWD

shell> keytool -import -noprompt -trustcacerts \
-alias mysql_ca_dest -file ca.pem \
-keystore security/tungsten_truststore.ts \
-storepass $PASSWD -keypass $PASSWD

If the global disable-security-controls=true setting is in place (i.e., replicator-to-cluster TLS is off) but you still want encrypted connections to MySQL, uncomment datasource-enable-ssl=true in conf/tungsten.ini.

Monitoring

The container exposes a Prometheus metrics endpoint on port 8091. Once the replicator is running, point your Prometheus scrape config at http://<host>:8091/metrics to collect standard replicator metrics including applied sequence number, latency, and pipeline state.

The REST API on port 8097 provides programmatic access to replicator state and operations, consistent with any other Tungsten Replicator deployment.

Lifecycle Operations

Stop the container

shell> docker stop replicator-alpha

Start it again

shell> docker start replicator-alpha

Because the THL and dynamic state are stored in host-mounted volumes (./thl/ and ./state/), the replicator resumes exactly where it left off — no resync needed.

Upgrade to a new version

Load the new image, update IMAGE_VERSION in .env, then:

shell> docker compose down
shell> docker compose up -d

The volumes are preserved across compose down / compose up cycles.

Remove the container and clean up

The following must be run from the original installation directory:

shell> docker compose down -v

Important

docker compose down -v also removes named volumes. If you want to preserve THL history for a future reinstall, back up the ./thl/ and ./state/ directories first.