Docker v2 Deployment

About 8 min

Docker v2 Deployment

This document describes how to deploy TimechoDB V2.0.10.1 and later versions with Docker Compose.

1. Environment Preparation

1.1 Host Requirements

Install the following components on the deployment host in advance:

Docker Engine
Docker Compose v2, which supports the docker compose command

Use the following commands to verify that Docker and Docker Compose are installed successfully:

docker --version
docker compose version

1.2 Obtain Deployment Files and Images

Contact Timecho to obtain the following files:

TimechoDB Docker image or compressed image package
Docker Compose deployment files

The Docker Compose deployment files include the following deployment patterns:

Deployment pattern	Compose file	Default memory limit	Description
1C1D standalone template	`docker-compose-1c1d.yml`	ConfigNode `2g`, DataNode `8g`	Starts 1 ConfigNode container and 1 DataNode container. Suitable for quick verification and small standalone environments.
1C2D cluster template	`docker-compose-cluster-1c2d.yml`	ConfigNode `2g`, each DataNode `8g`	Starts 1 ConfigNode container and 2 DataNode containers.
3C3D cluster template	`docker-compose-cluster-3c3d.yml`	Each ConfigNode `2g`, each DataNode `8g`	Starts 3 ConfigNode containers and 3 DataNode containers.
Single ConfigNode	`docker-compose-confignode.yml`	`2g`	Starts only a ConfigNode, for separated deployment or custom orchestration.
Single DataNode	`docker-compose-datanode.yml`	`8g`	Starts only a DataNode, for separated deployment or custom orchestration.

The values above are the default values in the compose templates, not unified capacity recommendations for production. In production environments, evaluate capacity again based on data volume, write load, query concurrency, retention period, and host resources. The actual available compose files are subject to the deployment package you receive.

1.3 Load the Image

If you receive a compressed image package, run the following commands on the deployment host:

docker load -i <image-package>.tar.gz
docker images

If the image has been pushed to an accessible image registry, log in to the registry and pull the image first:

docker login <registry>
docker pull <registry>/timecho/timechodb:<version>-standalone

1.4 Image Description

The TimechoDB image tag format is as follows:

<registry>/timecho/timechodb:<version>-standalone

Where:

Field	Meaning
`<registry>`	Image registry address
`timecho/timechodb`	Image repository path
`<version>-standalone`	Image tag

1.5 Modify the Image Version

Before deployment, check the image field in the compose file and replace it with the actual image name. For example:

image: timecho/timechodb:<version>-standalone

If you use a private image registry, specify the complete image address:

image: <registry>/timecho/timechodb:<version>-standalone

1.6 Recommended Resource Configuration

Deployment object	Default memory limit	Recommendation
1C1D Compose	ConfigNode `2g`, DataNode `8g`	For quick deployment, demos, and standalone testing. Adjust by workload in production.
1C2D cluster template	ConfigNode `2g`, each DataNode `8g`	For verifying multiple DataNode registration, queries, and basic cluster behavior.
3C3D cluster template	Each ConfigNode `2g`, each DataNode `8g`	For verifying multi-ConfigNode and multi-DataNode cluster deployment.
Single ConfigNode	`2g`	For separated deployment or custom orchestration.
Single DataNode	`8g`	For separated deployment or custom orchestration.

2. 1C1D Deployment

A 1C1D deployment starts 1 ConfigNode container and 1 DataNode container. It is suitable for quick deployment, functional verification, demo environments, and small standalone environments.

2.1 Prepare Directories

The following example stores deployment files and data directories under /docker-timechodb:

/docker-timechodb
├── docker-compose-1c1d.yml
└── data

Enter the deployment directory:

cd /docker-timechodb

2.2 Check the Compose Configuration

Open docker-compose-1c1d.yml and focus on the following fields:

Field	Example value	Description
`image`	`timecho/timechodb:<version>-standalone`	ConfigNode and DataNode use the same image.
`command`	`confignode`, `datanode`	Distinguishes the role by the container startup command.
`mem_limit`	ConfigNode `2g`, DataNode `8g`	Sets an independent memory limit for each container.
`ports`	`6667:6667`	Usually only the DataNode client port needs to be mapped to the host.
`volumes`	`./data/confignode:/iotdb/data`, `./data/datanode1:/iotdb/data`	Independent data directories are recommended for different roles.

If activation or log retention is required, make sure the corresponding directories are mounted in the compose file, for example:

volumes:
  - ./activation:/iotdb/activation
  - ./data/datanode1:/iotdb/data
  - ./logs/datanode1:/iotdb/logs

2.3 Create the Docker Network

docker-compose-1c1d.yml uses the external Docker network timechodb by default. Create this network before the first startup:

docker network create --subnet=172.18.0.0/16 timechodb

If the network already exists, you can ignore the duplicate creation message.

2.4 Start Services

docker compose -f docker-compose-1c1d.yml up -d

Check container status:

docker ps

View logs:

docker logs -f timechodb-confignode
docker logs -f timechodb-datanode-1

2.5 Activate

After the containers start, see 5. Database Activation.

2.6 Verify the Deployment

Enter the DataNode container and run the CLI:

docker exec -it timechodb-datanode-1 start-cli.sh

Run the following command in the CLI:

show cluster;

You should see ConfigNode and DataNode information, and the node status should be running normally.

3. Separated ConfigNode and DataNode Deployment Across Machines

This mode applies when ConfigNode and DataNode are deployed on different servers, or when each node must be managed separately according to machine, network, storage, and O&M requirements.

This mode usually uses docker-compose-confignode.yml to start ConfigNode on the ConfigNode server, and docker-compose-datanode.yml to start DataNode on the DataNode server. Before deployment, make sure the servers can communicate with each other and configure node addresses as IP addresses or domain names that are accessible from other machines.

3.1 Deploy ConfigNode

Enter the compose directory on the ConfigNode server:

cd docker_v2/src/main/DockerCompose

Modify docker-compose-confignode.yml:

Field	Example value	Description
`image`	`customer-registry.example.com/timecho/timechodb:<version>-standalone`	Replace it with the actual image available in the customer environment.
`command`	`["confignode"]`	Starts the ConfigNode role.
`cn_internal_address`	`confignode-1.example.com`	Set it to the ConfigNode address accessible from the DataNode machine.
`cn_internal_port`	`10710`	ConfigNode internal communication port, which must be open to other nodes.
`cn_consensus_port`	`10720`	ConfigNode consensus port. It must be reachable among ConfigNodes when multiple ConfigNodes are deployed.

Start ConfigNode:

docker network create --subnet=172.18.0.0/16 timechodb 2>/dev/null || true
docker compose -f docker-compose-confignode.yml up -d

View ConfigNode logs:

docker logs -f timechodb-confignode

3.2 Deploy DataNode

Enter the compose directory on the DataNode server:

cd docker_v2/src/main/DockerCompose

Modify docker-compose-datanode.yml:

Field	Example value	Description
`image`	`customer-registry.example.com/timecho/timechodb:<version>-standalone`	Replace it with the actual image available in the customer environment.
`command`	`["datanode"]`	Starts the DataNode role.
`dn_seed_config_node`	`confignode-1.example.com:10710`	Set it to the accessible address and port of the ConfigNode server.
`dn_internal_address`	`datanode-1.example.com`	Set it to the DataNode address accessible from other nodes.
`dn_rpc_port`	`6667`	Client RPC port.
`dn_mpp_data_exchange_port`	`10740`	MPP data exchange port, which must be reachable among DataNodes.
`dn_schema_region_consensus_port`	`10750`	SchemaRegion consensus port.
`dn_data_region_consensus_port`	`10760`	DataRegion consensus port.

Start DataNode:

docker network create --subnet=172.18.0.0/16 timechodb 2>/dev/null || true
docker compose -f docker-compose-datanode.yml up -d

View DataNode logs:

docker logs -f timechodb-datanode

3.3 Activate

After ConfigNode and DataNode start, see 5. Database Activation.

3.4 Verify Cluster Status

docker exec -it timechodb-datanode start-cli.sh

Run the following command in the CLI:

show cluster;

You should see at least 1 ConfigNode and 1 DataNode.

4. Multi-Node Template Deployment

If the deployment package provides multi-node compose templates, you can use them to quickly start a 1C2D or 3C3D cluster. Before deployment, make sure the host has sufficient resources and adjust the mem_limit of each service based on actual resources.

4.1 1C2D Cluster

The 1C2D template starts:

Role	Container
ConfigNode	`timechodb-confignode`
DataNode	`timechodb-datanode-1`, `timechodb-datanode-2`

Start:

docker compose -f docker-compose-cluster-1c2d.yml up -d

Check status:

docker ps
docker logs -f timechodb-confignode
docker logs -f timechodb-datanode-1

After the containers start, see 5. Database Activation.

Stop:

docker compose -f docker-compose-cluster-1c2d.yml down

4.2 3C3D Cluster

The 3C3D template starts:

Role	Container
ConfigNode	`timechodb-confignode-1`, `timechodb-confignode-2`, `timechodb-confignode-3`
DataNode	`timechodb-datanode-1`, `timechodb-datanode-2`, `timechodb-datanode-3`

This template is usually used to verify multi-node deployment and high availability. Before deployment, make sure the replica count, consensus protocol, ports, and memory configuration meet actual environment requirements.

Start:

docker compose -f docker-compose-cluster-3c3d.yml up -d

Check status:

docker ps
docker logs -f timechodb-confignode-1
docker logs -f timechodb-datanode-1

After the containers start, see 5. Database Activation.

Stop:

docker compose -f docker-compose-cluster-3c3d.yml down

5. Database Activation

Docker deployment supports command activation and file activation.

5.1 Command Activation

Enter any DataNode container that can connect to the database and start the CLI:

docker exec -it timechodb-datanode-1 start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw TimechoDB@2021

Run the following statement in the CLI to obtain the machine code required for activation:

show system info;

Run the following statement to obtain the version of the database to be activated:

show version;

Provide the machine code and version number to Timecho technical support. After you obtain the activation code, run the following command in the CLI:

activate '<activation-code>';

Replace <activation-code> with the actual activation code. Keep the single quotation marks around the activation code.

5.2 File Activation

If you use file activation, after ConfigNode and DataNode are started for the first time, a system_info file is generated in the host directory mounted to /iotdb/activation. Provide this file to Timecho technical support, and place the returned license file in the activation directory of the corresponding node.

When multiple ConfigNodes are deployed, collect the system_info file of each corresponding ConfigNode node, and place the returned license file in the activation directory of the corresponding node.

After the license file is placed, start the service again. For example, for a 1C1D deployment, run:

docker compose -f docker-compose-1c1d.yml up -d

5.3 Verify Activation

After entering the CLI, run:

show activation;

When ClusterActivationStatus in the result is ACTIVATED, activation is successful.

6. Key Configuration Notes

6.1 Container Roles

The TimechoDB Docker v2 image distinguishes roles by the container startup command:

command	Started role
`confignode`	Starts only ConfigNode
`datanode`	Starts only DataNode

6.2 Override Configuration with Environment Variables

When the container starts, replace-conf-from-env.sh reads lowercase environment variables and writes them to /iotdb/conf/iotdb-system.properties by configuration item name. The cn_*, dn_*, consensus protocol, and replica number configurations in the compose templates all use this mechanism.

Pay attention to the following when using environment variables:

The environment variable name must be exactly the same as the configuration key in properties. Substrings such as xxx_key are not matched.
If a valid key= line exists in the file, the valid line is replaced first. Only when no valid line exists is the value inserted after the #key= commented line.
The configuration value must be a single line. Values containing line breaks or carriage returns are skipped.
Characters such as /, &, and backslashes are written as ordinary values.

6.3 Data and Log Directories

Path in container	Purpose
`/iotdb/data`	TimechoDB data directory
`/iotdb/logs`	TimechoDB log directory
`/iotdb/activation`	Activation-related file directory
`/iotdb/conf`	Configuration file directory

In production environments, mount data and log directories to independent data disks or specified host directories, and back them up regularly.

6.4 Ports

Port	Configuration item	Purpose
`6667`	`dn_rpc_port`	Client RPC access port
`10710`	`cn_internal_port`	ConfigNode internal communication port
`10720`	`cn_consensus_port`	ConfigNode consensus port
`10740`	`dn_mpp_data_exchange_port`	DataNode MPP data exchange port
`10750`	`dn_schema_region_consensus_port`	DataNode SchemaRegion consensus port
`10760`	`dn_data_region_consensus_port`	DataNode DataRegion consensus port

By default, only 6667 needs to be mapped to the host for client access. Other ports are used for internal cluster communication and are not recommended to be exposed outside the host unless necessary.

6.5 Mount the Configuration Directory

If you need to maintain configuration files directly on the host, copy the configuration directory from the container first:

docker cp timechodb-datanode-1:/iotdb/conf ./conf

Then add the configuration directory mount to the compose file:

volumes:
  - ./conf:/iotdb/conf

Restart the service after modifying the mount:

docker compose -f docker-compose-1c1d.yml up -d

7. Common O&M Commands

View containers:

docker ps

View logs:

docker logs -f timechodb-confignode
docker logs -f timechodb-datanode-1

Enter a container:

docker exec -it timechodb-datanode-1 bash

View the container memory limit:

docker inspect timechodb-datanode-1 --format '{{.HostConfig.Memory}}'

Stop services:

docker compose -f docker-compose-1c1d.yml down

Stop services in separated deployment:

docker compose -f docker-compose-datanode.yml down
docker compose -f docker-compose-confignode.yml down

8. Upgrade

Before upgrading, back up the data directory, log directory, and configuration directory on the host.

Obtain the image of the new version, and import it to the deployment host by docker load or docker pull.
Modify the image tag in the compose file.
Stop the old containers.
Start containers with the new image.
Use show cluster; to verify node status.

1C1D deployment example:

docker compose -f docker-compose-1c1d.yml down
docker compose -f docker-compose-1c1d.yml up -d

Separated deployment example:

docker compose -f docker-compose-datanode.yml down
docker compose -f docker-compose-confignode.yml down
docker compose -f docker-compose-confignode.yml up -d
docker compose -f docker-compose-datanode.yml up -d

9. FAQ

9.1 Failed to Pull or Load the Image

Check the following:

Whether the image file is complete.
Whether the image in the compose file is consistent with the local image name.
If a private image registry is used, whether the deployment host can access the registry.
If a private image registry is used, whether docker login has been executed.

9.2 Container Exits Immediately After Startup

View container logs:

docker logs timechodb-confignode
docker logs timechodb-datanode-1

Focus on the following:

Whether the image version is correct.
Whether command is confignode or datanode.
Whether the data directory, log directory, and activation directory have write permissions.
Whether mem_limit is too small.
Whether activation has been completed.

9.3 DataNode Cannot Register with ConfigNode

Check the following:

Whether the timechodb Docker network exists.
Whether the ConfigNode container has started normally.
Whether dn_seed_config_node in DataNode points to the correct ConfigNode name and port.
Whether ConfigNode and DataNode are in the same Docker network.

Example commands:

docker network inspect timechodb
docker logs timechodb-confignode
docker logs timechodb-datanode

9.4 Port 6667 Conflict

If another service on the host already occupies 6667, modify the port mapping in the compose file:

ports:
  - "16667:6667"

After modification, clients should connect to port 16667 on the host.

9.5 Service Exits After Generating Machine Information on First Startup

It is normal for the service to exit after system_info is generated on first startup. Place the license file and start the service again.