Deploy OceanBase Database in a container|V4.3.5| docs|Distributed Database

Deploy OceanBase Database in a container

Last Updated：2025-12-02 06:03:32 Updated

This topic explains how to deploy a single-node OceanBase database in a Docker container.

Notice

The operations described in this topic are intended for learning or testing purposes only. Do not apply them to production environments.

Prerequisites

Before proceeding with the operations described in this topic, make sure that:

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

Note

On x86-based Mac servers, only Docker Docker V4.9.0 or earlier are supported for deploying the OceanBase database. To obtain Docker V4.9.0 or earlier, click here.
Your machine meets the software and hardware requirements. For more information, see Hardware and software requirements.

Deploy OceanBase Database

(Optional) Step 1: Pull the image of OceanBase Database

Run the following commands to pull the image of OceanBase Database.

Search for images related to OceanBase Database.

[admin@test001 ~]$ sudo docker search oceanbase

Pull the latest image of OceanBase Database.
```
[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 update the repository address in the command from Step 2, make sure to also update the repository address in the command from Step 3. Both commands 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 an 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 -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 -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

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 username for the created user tenant is set to test by default and cannot be modified.

shell dmin@test001 ~]$ sudo docker run -p 2881:2881 -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 is used to map a port of the container to a port on the host. In the example, it maps port 2881 in the container to port 2881 on the host.
-v is used to share files or directories between the container and the host for data persistence or configuration sharing. By default, the system deploys OceanBase Database in the /root/ob directory and saves its configurations in the /root/.obd/cluster directory in the container. You can use this option to persist data on the host.

You can also use the -v option to mount a folder containing the SQL statements to be executed. Here is an example. You need to replace {init_sql_folder_path} with the actual path of the initialization SQL file.
```
[admin@test001 ~]$ sudo docker run -p 2881:2881 -v {init_sql_folder_path}:/root/boot/init.d --name obstandalone -e MODE=SLIM -d oceanbase/oceanbase-ce
```
--name is used to set the name of the Docker container, such as obstandalone in the above example.
-e is used to set environment variables. In the example above, MODE is used to set the startup mode of OceanBase Database, and OB_TENANT_PASSWORD is used to set the password of the root@test user in OceanBase Database. For more information about environment variables, see the Supported environment variables section below.

Note

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

The startup is expected to take 2 to 5 minutes. Run the following command, and if it returns boot success!, the startup was successful.

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

Step 3: Connect to the OceanBase Database instance

The oceanbase-ce image includes OceanBase Deployer (obd) and OceanBase Client (OBClient). You can either enter the container and use obd commands and OBClient to manage and connect to the instance, or you can use a local OBClient on your host machine or a MySQL client to connect to the OceanBase Database instance.

Connect to the instance after you enter the container

Enter the Docker container.

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

View details about the cluster.

# 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 to the instance from your host machine

You can use a local OBClient on your host machine or a MySQL client to connect to the OceanBase Database instance. Here is an example of connecting to the instance from your host machine using the OBClient:

[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 user will use a password of an empty string by default.

After the connection is established, your terminal will display the following message:

Welcome to the OceanBase.  Commands end with ; or \g.
Your OceanBase connection id is 3221711319
Server version: OceanBase_CE 4.3.0.1 (r100000242024032211-0193a343bc60b4699ec47792c3fc4ce166a182f9) (Built Mar 22 2024 13:19:48)

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)]>

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 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 username of the user tenant defaults to and must be `test`. The configuration of other values is 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 in the `OB_TENANT_NAME` tenant. If `OB_TENANT_NAME` is not configured, the default value `root@test` will be used.
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`.