Deploy OceanBase Database in a container environment|V4.4.2| docs|Distributed Database

Deploy OceanBase Database in a container environment

Last Updated：2026-03-10 02:48:23 Updated

This topic describes how to deploy a single-node OceanBase Database in a Docker container.

Notice

The operations in this topic are only applicable to learning or testing scenarios. Do not apply them to a production environment.

Prerequisites

Before you proceed, make sure that the following conditions are met:

You have installed and started Docker. For more information, see Docker documentation.

Note

On x86-based Mac computers, you can deploy OceanBase Database only by using Docker V4.9.0 or earlier. To download Docker, click here.
Your machine meets the software and hardware requirements. For more information, see Software and hardware requirements.

Deploy OceanBase Database

(Optional) Step 1: Pull the OceanBase Database image

Run the following commands to pull the required image for OceanBase Database.

Search for the OceanBase Database image.

[admin@test001 ~]$ sudo docker search oceanbase

Pull the latest OceanBase Database image.
```
[admin@test001 ~]$ sudo docker pull oceanbase/oceanbase-ce
```
Note
- If you are unable to pull the image, you can try pulling it from the quay.io or ghcr.io repositories instead. To do so, replace oceanbase/oceanbase-ce with quay.io/oceanbase/oceanbase-ce or ghcr.io/oceanbase/oceanbase-ce in the pull command. For example, sudo docker pull quay.io/oceanbase/oceanbase-ce.
- When you change the repository address in the commands in this step, you must also update the repository address in the commands in Step 2. Both steps must use the same repository.
- By default, the above command pulls the latest version of image. You can also select an image from dockerhub, quay.io, or ghcr.io as needed.

Step 2: Start the OceanBase Database instance

Run the following command to start an OceanBase Database instance.

Deploy an instance with the maximum specifications supported by the container

Deploy a mini standalone instance

Deploy an instance in quick start mode

[admin@test001 ~]$ sudo docker run -p 2881:2881 -p 2886:2886 -v $PWD/ob:/root/ob -v $PWD/obd/cluster:/root/.obd/cluster --name obstandalone -e MODE=NORMAL -e OB_TENANT_PASSWORD=***** -d oceanbase/oceanbase-ce

[admin@test001 ~]$ sudo docker run -p 2881:2881 -p 2886:2886 -v $PWD/ob:/root/ob -v $PWD/obd/cluster:/root/.obd/cluster --name obstandalone -e MODE=MINI -e OB_TENANT_PASSWORD=***** -d oceanbase/oceanbase-ce

In quick start mode, if you configure tenant and resource-related environment variables, all variables except OB_TENANT_PASSWORD and OB_SYS_PASSWORD will be ignored. The created user tenant name defaults to and can only be test.

[admin@test001 ~]$ sudo docker run -p 2881:2881 -p 2886:2886 -v $PWD/ob:/root/ob -v $PWD/obd/cluster:/root/.obd/cluster --name obstandalone -e MODE=SLIM -d oceanbase/oceanbase-ce

The options in the example work as follows:

-p maps container ports to host ports. In the example, ports 2881 and 2886 in the container are mapped to ports 2881 and 2886 on the host respectively.
-v shares files or directories between the container and the host for data persistence or configuration sharing. By default, OceanBase Database is deployed in the /root/ob directory in the container, and its configuration is saved in /root/.obd/cluster. You can use this option to persist data on the host.

You can also use the -v option to mount SQL files for execution. Replace {init_sql_folder_path} with the actual path to your init SQL files:
```
[admin@test001 ~]$ sudo docker run -p 2881:2881 -p 2886:2886 -v {init_sql_folder_path}:/root/boot/init.d --name obstandalone -e MODE=SLIM -d oceanbase/oceanbase-ce
```
--name sets the Docker container name. For example, the example creates a container named obstandalone.
-e sets environment variables. In the example, MODE sets the OceanBase Database startup mode, and OB_TENANT_PASSWORD sets the root@test user password in OceanBase Database. For more information about environment variables, see Supported environment variables below.

Note

enable_rich_error_msg is enabled by default when Docker starts. If an error occurs, you can use the trace command to obtain detailed error information.

It takes about 2 to 5 minutes to start the instance. Run the following command. If the output is boot success!, the instance is started.

[admin@test001 ~]$ sudo docker logs obstandalone | tail -1
boot success!

Step 3: Connect to the OceanBase Database instance

The oceanbase-ce image includes obd (OceanBase Deployer, an OceanBase installation and deployment tool) and OBClient (OceanBase command-line client). You can enter the container and use the obd command and OBClient client to manage and connect to the instance, or you can use the OBClient or MySQL client on the host to connect to the OceanBase Database instance.

Connect after entering the container

Enter the Docker container.

[admin@test001 ~]$ sudo docker exec -it obstandalone bash

View the cluster details.

# View the list of clusters
obd cluster list
# View the details of the obcluster cluster
obd cluster display obcluster

Connect to the cluster.

obclient -h127.0.0.1 -uroot@sys -A -Doceanbase -P2881 -p

Connect using the local client on the host

You can use the OBClient or MySQL client on the host to connect to the OceanBase Database instance. Here is an example:

[admin@test001 ~]$ obclient -uroot@sys -h127.0.0.1 -P2881 -p

Note

If you do not configure a password through an environment variable when you start the OceanBase Database instance, the created users use an empty password by default.

After the connection is successful, the terminal displays the following content:

Welcome to the OceanBase.  Commands end with ; or \g.
Your OceanBase connection id is 3221711319
Server version: OceanBase_CE 4.3.5.3 (r103010012025090210-8b80b225c2dcba7dd0c83f3d5a24e3c1ffc03f24) (Built Sep  2 2025 10:25:24)

Copyright (c) 2000, 2018, OceanBase and/or its affiliates. All rights reserved.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

obclient [(none)]>

Step 4: Access the obshell Dashboard management page

You can access the obshell Dashboard management page provided by obshell by accessing port 2886 on the host.

Supported environment variables

Variable	Default value	Valid values	Description
MODE	MINI	`MINI`: indicates that the container will start the cluster with minimum resources. `NORMAL`: indicates that the container will start the cluster with all available resources of the container. `SLIM`: indicates that the container will start only OceanBase Database in quick-start mode. Note If `MODE` is set to `SLIM`, any configuration of tenant and resource-related environment variables except `OB_TENANT_PASSWORD` and `OB_SYS_PASSWORD` will be ignored.	Set the cluster startup mode.
EXIT_WHILE_ERROR	true	`true`: indicates that the container will exit when OceanBase Database fails to start. `false`: indicates that the container will not exit when OceanBase Database fails to start. You can log in to the container for debugging.	Control whether to exit the container when OceanBase Database fails to start.
OB_CLUSTER_NAME	obcluster	N/A	Set the name of the OceanBase cluster.
OB_TENANT_NAME	test	The tenant name must be 63 bytes or less in length and can contain only uppercase and lowercase English letters, numbers, and underscores, and cannot be an OceanBase keyword.	After configuration, a MySQL-compatible tenant with the same name will be created in the OceanBase cluster. If not configured, the default tenant named `test` will be created. Note When `MODE` is set to `SLIM`, the user tenant name defaults to and can only be `test`. Other values are ignored.
OB_MEMORY_LIMIT	6G	[6G, +∞)	Set the total memory size available to the OceanBase cluster. This setting is equivalent to that of the memory_limit parameter in other two solutions.
OB_DATAFILE_SIZE	5G	[5G, +∞)	Set the size of data files in the OceanBase cluster. This setting is equivalent to that of the datafile_size parameter in other two solutions.
OB_LOG_DISK_SIZE	5G	[5G, +∞)	Set the size of the redo log disk in the OceanBase cluster. This setting is equivalent to that of the log_disk_size parameter in other two solutions.
OB_SYS_PASSWORD	Empty string	The password must be a string with no special requirements.	Set the password of the administrator user (root@sys) in the sys tenant of the OceanBase cluster.
OB_TENANT_PASSWORD	Empty string	The password must be a string with no special requirements.	Set the password of the administrator user of the tenant specified by `OB_TENANT_NAME`. If `OB_TENANT_NAME` is not configured, this password applies to the root@test user.
OB_SYSTEM_MEMORY	1G	[1G, +∞)	Set the memory size reserved for the tenant with ID `500` in the OceanBase cluster. This setting is equivalent to that of the system_memory parameter in other two solutions.
OB_TENANT_MIN_CPU	N/A	/	Set the minimum CPU specifications for the `OB_TENANT_NAME` tenant in the OceanBase cluster. If not configured, the tenant will occupy all the remaining resources of the cluster. This setting is equivalent to that of the `MIN_CPU` parameter in the resource unit creation solution. For more information, see CREATE RESOURCE UNIT.
OB_TENANT_MEMORY_SIZE	N/A	/	Set the memory specifications for the `OB_TENANT_NAME` tenant in the OceanBase cluster. If not configured, the tenant will occupy all the remaining resources of the cluster. This setting is equivalent to that of the `MEMORY_SIZE` parameter in the resource unit creation solution. For more information, see CREATE RESOURCE UNIT.
OB_TENANT_LOG_DISK_SIZE	N/A	/	Set the size of the log disk for the `OB_TENANT_NAME` tenant in the OceanBase cluster. If not configured, the tenant will occupy all the remaining resources of the cluster. This setting is equivalent to that of the `LOG_DISK_SIZE` parameter in the resource unit creation solution. For more information, see CREATE RESOURCE UNIT.
OB_CONFIGSERVER_ADDRESS	N/A	/	Set the address of obconfigserver. For example: `http://10.10.10.1:8080`.