Docker Deployment
You can deploy TDengine services in Docker containers and use environment variables in the docker run command line or docker-compose file to control the behavior of services in the container.
Custom Passwords, Upgrades, and Health Checks
If you use a custom root password, note the behavior differences across Docker image versions:
- For
3.3.6.6-3.3.8.4, if the root password had already been changed in an older image, create an empty.docker-entrypoint-root-password-changedfile in the data directory (default/var/lib/taos) before starting the container again. - For
3.3.8.8and later, provide the current root password throughTAOS_ROOT_PASSWORDorTAOS_ROOT_PASSWORD_FILE. The image can be upgraded directly, but if the root password was changed previously, the deployment configuration must still provide the current password before a restart, image upgrade, or Pod recreation. - For
3.4.1.0and later,taos-check startupandtaos-check serviceare available for health checks.taos-check serviceuses the same password source, so stale password configuration will also break health checks and other components that authenticate with the root account.
The following sections on hostname, docker compose, and Kubernetes probes do not repeat the same version matrix. Whenever root password changes, image upgrades, or taos-check behavior are involved, the rules above apply.
Starting TDengine
The TDengine image is launched with HTTP service activated by default. Use the following command to create a containerized TDengine environment with HTTP service.
docker run -d --name tdengine \
--hostname tdengine -e TAOS_FQDN=tdengine \
-v ~/data/taos/dnode/data:/var/lib/taos \
-v ~/data/taos/dnode/log:/var/log/taos \
-p 6041:6041 tdengine/tsdb-ee
Detailed parameter explanations are as follows:
- /var/lib/taos: Default data file directory for TDengine, can be modified through the configuration file.
- /var/log/taos: Default log file directory for TDengine, can be modified through the configuration file.
The above command starts a container named tdengine and maps the HTTP service's port 6041 to the host port 6041. The following command can verify if the HTTP service in the container is available.
curl -u root:taosdata -d "show databases" localhost:6041/rest/sql
Run the following command to access TDengine within the container.
$ docker exec -it tdengine taos
taos> show databases;
name |
=================================
information_schema |
performance_schema |
Query OK, 2 rows in database (0.033802s)
Within the container, TDengine CLI or various connectors (such as JDBC-JNI) connect to the server via the container's hostname. Accessing TDengine inside the container from outside is more complex, and using RESTful/WebSocket connection methods is the simplest approach.
Preserve Node Identity When Recreating Containers
For new images built using image installation mode, TDengine defaults to the runtime container hostname when fqdn is not specified through TAOS_FQDN or a configuration file. The build container hostname is not retained. --hostname (short form -h) sets the container hostname; --name only sets the container name. Docker generates a hostname if --hostname is omitted.
For a fresh deployment, explicitly set a stable hostname and TAOS_FQDN as shown above. Restarting the same container normally retains its hostname, but recreating it can change an automatically generated hostname. When reusing a data directory or upgrading the image, retain the original node FQDN. Historical images may use localhost or another value; do not replace it with the example value tdengine.
Before deleting the old container, record the node endpoint:
docker exec tdengine taos -s "show dnodes;"
For example, if the original endpoint is old-node:6030, mount the same data directory and use --hostname old-node -e TAOS_FQDN=old-node when recreating the container, retaining the original port configuration. Other nodes in a cluster must also be able to resolve and reach that address. Do not manually edit node identity files in the data directory.
Starting TDengine in host network mode
Run the following command to start TDengine in host network mode, which allows using the host's FQDN to establish connections, rather than using the container's hostname.
docker run -d --name tdengine --network host tdengine/tsdb-ee
This method is similar to starting TDengine on the host using the systemctl command. If the TDengine client is already installed on the host, you can directly use the following command to access the TDengine service.
$ taos
taos> show dnodes;
id | endpoint | vnodes | support_vnodes | status | create_time | note |
=================================================================================================================================================
1 | vm98:6030 | 0 | 32 | ready | 2022-08-19 14:50:05.337 | |
Query OK, 1 rows in database (0.010654s)
Start TDengine with a specified hostname and port
- Default FQDN values vary across historical images. When upgrading or reusing a data directory, retain the original node FQDN as described in Preserve Node Identity When Recreating Containers.
- For root password changes, image upgrades, or
taos-checkbehavior, follow the version-specific rules described earlier in this section.
Use the following command to establish a connection on a specified hostname using the TAOS_FQDN environment variable or the fqdn configuration item in taos.cfg. This method provides greater flexibility for deploying TDengine.
docker run -d \
--name tdengine \
--hostname tdengine \
-e TAOS_FQDN=tdengine \
-p 6030:6030 \
-p 6041-6049:6041-6049 \
-p 6041-6049:6041-6049/udp \
tdengine/tsdb-ee
First, the above command starts a TDengine service in the container, listening on the hostname tdengine, and maps the container's port 6030 to the host's port 6030, and the container's port range [6041, 6049] to the host's port range [6041, 6049]. If the port range on the host is already in use, you can modify the command to specify a free port range on the host.
Secondly, ensure that the hostname tdengine is resolvable in /etc/hosts. Use the following command to save the correct configuration information to the hosts file.
echo 127.0.0.1 tdengine |sudo tee -a /etc/hosts
Finally, you can access the TDengine service using the TDengine CLI with tdengine as the server address, as follows.
taos -h tdengine -P 6030
If TAOS_FQDN is set to the same as the hostname of the host, the effect is the same as "starting TDengine in host network mode".
Launching the Cluster with Docker Compose
Use the following Docker Compose configuration file to bring up a 3-node TDengine TSDB cluster. Contents of docker-compose.yaml:
services:
td1:
image: tdengine/tsdb-ee
environment:
- TAOS_FQDN=td1
td2:
image: tdengine/tsdb-ee
environment:
- TAOS_FQDN=td2
- TAOS_FIRST_EP=td1:6030
td3:
image: tdengine/tsdb-ee
environment:
- TAOS_FQDN=td3
- TAOS_FIRST_EP=td1:6030
The environment variable TAOS_FIRST_EP specifies the endpoint of the first dnode to connect to in the cluster, equivalent to the firstEp parameter in /etc/taos/taos.cfg. If the cluster uses a custom root password, add the corresponding password environment variable to each service definition and keep it synchronized with the actual database password. Version-specific upgrade and compatibility behavior is the same as described earlier in this section. Start the cluster:
docker compose up
After the cluster is up, enter any node, for example, the td1 node:
docker compose exec td1 bash
And execute the following command to check the cluster status:
$ taos -s "show dnodes"
Welcome to the TDengine Command Line Interface, Native Client Version:3.3.6.13
Copyright (c) 2025 by TDengine, all rights reserved.
taos> show dnodes
id | endpoint | vnodes | support_vnodes | status | create_time | reboot_time | note |
=============================================================================================================================================================================
1 | td1:6030 | 0 | 85 | ready | 2025-08-21 01:56:41.630 | 2025-08-21 01:56:41.462 | |
2 | td2:6030 | 1 | 85 | ready | 2025-08-21 01:56:43.203 | 2025-08-21 01:56:43.453 | |
3 | td3:6030 | 0 | 85 | ready | 2025-08-21 01:56:43.296 | 2025-08-21 01:56:43.491 | |
Query OK, 3 row(s) in set (0.006355s)