Running YDB in Docker

• Connection parameters
• Installation
• Starting
  • Startup parameters
• Making queries
• Stopping
• License and components

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

Connection parameters

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

gRPC

gRPCs/TLS

• Endpoint: grpc://localhost:2136
• Database location: /local

• Authentication: Anonymous (without authentication)

• Endpoint: grpcs://localhost:2135

• Database location: /local
• Authentication: Anonymous (without authentication)

Installation

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

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

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 means mounting the host system directories into a container like <host system directory>:<mount directory in 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>. 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 disk for storing data in <NUM>GB format (for example, YDB_PDISK_SIZE=128GB). Acceptable values: 64GB and higher. Defaults to 64GB.
• 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 M1 in this mode only.

-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 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 localhost:2136 -d /local scheme ls

, where

<container_id>: The container ID output when you start it.

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