Use Docker Compose to quickly deploy a TiKV testing cluster on a single machine.

We are currently refactoring our documentation. Please excuse any problems you may find and report them here.

This guide describes how to quickly deploy a TiKV testing cluster using Docker Compose on a single machine. Currently, this installation method only supports the Linux system.


Make sure you have installed the following items on your machine:

  • Docker (17.06.0 or later) and Docker Compose

    sudo yum install docker docker-compose
  • Git

    sudo yum install git


Download tidb-docker-compose.

git clone https://github.com/pingcap/tidb-docker-compose.git

Prepare cluster

In this example, let’s run a simple cluster with only 1 PD server and 1 TiKV server. See the following for the basic docker compose configuration file:

version: '2.1'

    image: pingcap/pd:latest
      - "2379"
      - ./config/pd.toml:/pd.toml:ro
      - ./data:/data
      - ./logs:/logs
      - --name=pd0
      - --client-urls=
      - --peer-urls=
      - --advertise-client-urls=http://pd0:2379
      - --advertise-peer-urls=http://pd0:2380
      - --initial-cluster=pd0=http://pd0:2380
      - --data-dir=/data/pd0
      - --config=/pd.toml
      - --log-file=/logs/pd0.log
    restart: on-failure
    image: pingcap/tikv:latest
      - ./config/tikv.toml:/tikv.toml:ro
      - ./data:/data
      - ./logs:/logs
      - --addr=
      - --advertise-addr=tikv0:20160
      - --data-dir=/data/tikv0
      - --pd=pd0:2379
      - --config=/tikv.toml
      - --log-file=/logs/tikv0.log
      - "pd0"
    restart: on-failure

All the following example docker compose config files must contain this base configuration.


Run YCSB to connect to the TiKV cluster:

  1. Create a ycsb-docker-compose.yml file, add the above base config to this file, and then append the following section:

      image: pingcap/go-ycsb
  2. Start the cluster:

    rm -rf data logs 
    docker-compose -f ycsb-docker-compose.yml pull 
    docker-compose -f ycsb-docker-compose.yml up -d
  3. Start YCSB:

    docker-compose -f ycsb-docker-compose.yml run ycsb shell tikv -p tikv.pd=pd0:2379
  4. Run YCSB:

    INFO[0000] [pd] create pd client with endpoints [pd0:2379]
    INFO[0000] [pd] leader switches to: http://pd0:2379, previous:
    INFO[0000] [pd] init cluster id 6628733331417096653
    » read a
    Read empty for a
    » insert a field0=0
    Insert a ok
    » read a
    Read a ok

Use Titan, a distributed implementation of Redis compatible layer, to connect to the TiKV cluster via the Redis protocol:

  1. Create a titan-docker-compose.yml file, add the above base config to this file, and then append the following section:

        image: meitu/titan
          - "7369:7369"
          - --pd-addrs=tikv://pd0:2379
          - "tikv0"
        restart: on-failure    
  2. Start the cluster:

    rm -rf data logs 
    docker-compose -f titan-docker-compose.yml pull
    docker-compose -f titan-docker-compose.yml up -d
  3. Use redis-cli to communicate with Titan:

    redis-cli -p 7369> set a 1
    OK> get a

What’s next?

  • If you want to try the Go client, see Try Two Types of APIs. You need to build your docker image and add it to the docker compose config file like above YCSB or Titan does.
  • If you want to run a full cluster with monitor support, please follow the tidb-docker-compose guide, comment the tidb and tispark sections out in the values.yaml, generate the new docker compose config, then add your own binary image and run it.