Running YDB in Docker

For debugging or testing, you can run the YDB Docker container.

It is recommended to use Docker 20.10.25 or newer. If you have an older version, you might need to add a --privileged or --security-opt seccomp=unconfined flag when running containers.

Connection parameters

As a result of completing the instructions below, you'll get a local YDB database that can be accessed using the following:

Installation

Download the current public version of the Docker image:

docker pull cr.yandex/yc/yandex-docker-local-ydb:latest

Make sure the Docker image has been pulled:

docker image list | grep cr.yandex/yc/yandex-docker-local-ydb

Output:

cr.yandex/yc/yandex-docker-local-ydb           latest   b73c5c1441af   2 months ago   793MB

Starting

The YDB Docker container uses the host system resources (CPU, RAM) within the limits allocated by the Docker settings.

The YDB Docker container stores data in its file system whose sections are reflected in the host system directory. The start container command given below will create files in the current directory, so first create a working directory and then start the container from it:

docker run -d --rm --name ydb-local -h localhost \
  -p 2135:2135 -p 8765:8765 -p 2136:2136 \
  -v $(pwd)/ydb_certs:/ydb_certs -v $(pwd)/ydb_data:/ydb_data \
  -e YDB_DEFAULT_LOG_LEVEL=NOTICE \
  -e GRPC_TLS_PORT=2135 -e GRPC_PORT=2136 -e MON_PORT=8765 \
  cr.yandex/yc/yandex-docker-local-ydb:latest

Warning

Currently, disk storage is not supported on Apple Silicon (M1 or M2). Use the command from "In-memory storage" tab if you want to try YDB on this CPU.

docker run -d --rm --name ydb-local -h localhost \
  -p 2135:2135 -p 8765:8765 -p 2136:2136 \
  -v $(pwd)/ydb_certs:/ydb_certs -v $(pwd)/ydb_data:/ydb_data \
  -e YDB_DEFAULT_LOG_LEVEL=NOTICE \
  -e GRPC_TLS_PORT=2135 -e GRPC_PORT=2136 -e MON_PORT=8765 \
  -e YDB_USE_IN_MEMORY_PDISKS=true \
  cr.yandex/yc/yandex-docker-local-ydb:latest

If started successfully, you'll see the ID of the created container.

Startup parameters

-d means running the Docker container in the background.

--rm means removing the container after its operation is completed.

--name is the container name. Specify ydb-local to be able to perform the below instructions for stopping the container by copying text through the clipboard.

-h is the container host name. Be sure to pass the localhost value. Otherwise, the container will be started with a random hostname.

-v: Mount the host system directories into a container as <host system directory>:<mount directory within the container>. The YDB container uses the following mount directories:

  • /ydb_data for storing data. If this directory is not mounted, the container will be started without saving data to the host system disk.
  • /ydb_certs for storing certificates to establish a TLS connection. The started container will write to this directory the certificates to be used for a TLS client connection. If this directory is not mounted, you won't be able to connect via TLS due to having no certificate information.

-e means setting environment variables in <name>=<value> format. The YDB container uses the following environment variables:

  • YDB_DEFAULT_LOG_LEVEL: The logging level. Acceptable values: CRIT, ERROR, WARN, NOTICE, and INFO. Defaults to NOTICE.
  • GRPC_PORT: The port for unencrypted connections. Defaults to 2136.
  • GRPC_TLS_PORT: The port for TLS connections. Defaults to 2135.
  • MON_PORT: The port for the built-in web UI with monitoring and introspection tools. Defaults to 8765.
  • YDB_PDISK_SIZE: The size of the data storage disk in <NUM>GB format (for example, YDB_PDISK_SIZE=128GB). Acceptable values: 80GB and higher. Defaults to 80GB.
  • YDB_USE_IN_MEMORY_PDISKS: Using disks in memory. Acceptable values are true and false, defaults to false. If enabled, the container's file system is not used for working with data, all data is only stored in the memory of a process and is lost when it's stopped. Currently, you can start the container on Apple Silicon (M1 or M2) in this mode only.

For YDB to work efficiently, we recommend using physical (not virtual) disks larger than 800 GB as block devices.

The minimum disk size is 80 GB, otherwise the YDB node won't be able to use the device. Correct and uninterrupted operation with minimum-size disks is not guaranteed. We recommend using such disks exclusively for informational purposes.

Warning

Configurations with disks less than 800 GB or any types of storage system virtualization cannot be used for production services or system performance testing.

We don't recommend storing YDB data on disks shared with other processes (for example, the operating system).

-p means publishing container ports on the host system. All applicable ports must be explicitly listed even if default values are used.

Note

It may take several minutes to initialize the Docker container, depending on the allocated resources. The database will not be available until the container is initialized.

Making queries

Install the YDB CLI and run a query, for example:

ydb -e grpc://localhost:2136 -d /local scheme ls

To ensure a connection using TLS is successful, add the name of the file with the certificate to the connection parameters. The query in the example below should be executed from the same working directory that you used to start the container:

ydb -e grpcs://localhost:2135 --ca-file ydb_certs/ca.pem -d /local scheme ls

A pre-built YDB CLI version is also available within the image:

docker exec <container_id> /ydb -e grpc://localhost:2136 -d /local scheme ls

, where

<container_id>: Container ID that is output when you start the container.

Stopping

When everything is done, stop a Docker container:

docker kill ydb-local

License and components

The Docker container root includes a file with the license agreement (LICENSE) and a list of the components used and their licenses (THIRD_PARTY_LICENSES).

Read the license agreement:

docker run --rm -it --entrypoint cat cr.yandex/yc/yandex-docker-local-ydb LICENSE

View all the included components and their licenses:

docker run --rm -it --entrypoint cat cr.yandex/yc/yandex-docker-local-ydb THIRD_PARTY_LICENSES