Running YDB in Docker
For debugging or testing, you can run the YDB Docker container.
As a result of completing the instructions below, you'll get a local YDB database that can be accessed using the following:
Upload 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
cr.yandex/yc/yandex-docker-local-ydb latest b73c5c1441af 2 months ago 793MB
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
If started successfully, you'll see the ID of the created container.
-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_datafor storing data. If this directory is not mounted, the container will be started without saving data to the host system disk.
/ydb_certsfor 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:
INFO. Defaults to
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>GBformat (for example,
YDB_PDISK_SIZE=128GB). Acceptable values:
80GBand higher. Defaults to 80GB.
YDB_USE_IN_MEMORY_PDISKS: Using disks in memory. Acceptable values are
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 M1 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.
Configurations with disks less than 800 GB or any types of storage system virtualization cannot be used for production services or system performance testing.
-p means publishing container ports on the host system. All applicable ports must be explicitly listed even if default values are used.
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.
Install the YDB CLI and execute queries as described in YDB CLI - Getting started, using the endpoint and database location specified at the beginning of this article. 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 precompiled version of the YDB CLI is also available within the image:
docker exec <container_id> /ydb -e grpc://localhost:2136 -d /local scheme ls
<container_id>: The container ID output when you start it.
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 (
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