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 machines, only Docker V4.9.0 or earlier is supported for deploying OceanBase Database. Click here to download Docker.
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 oceanbasePull the latest image of OceanBase Database.
[admin@test001 ~]$ sudo docker pull oceanbase/oceanbase-ceNote
If you are unable to pull the image, you can try pulling it from the
quay.ioorghcr.iorepositories instead. To do so, replaceoceanbase/oceanbase-cewithquay.io/oceanbase/oceanbase-ceorghcr.io/oceanbase/oceanbase-cein the pull command. For example,sudo docker pull quay.io/oceanbase/oceanbase-ce.When you update the repository address in the command in this step, make sure to also update the repository address in the command in Step 2. 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.
[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 name of the created user tenant is set to test by default and cannot be modified.
[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 following describes the options in the example:
-pis used to map a port of the container to a port of the host machine. In the example, ports2881and2886of the container are mapped to ports2881and2886of the host machine, respectively.-vis used to share files or directories between the container and the host machine to persist data or share configurations. By default, the system deploys OceanBase Database in the/root/obdirectory of the container and saves its configuration in the/root/.obd/clusterdirectory. You can use this option to persist data on the host machine.You can also use the
-voption to mount the SQL scripts to be executed. In the following example, replace{init_sql_folder_path}with the actual path of the initialization SQL file.[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--nameis used to set the name of the Docker container, such asobstandalonein the above example.-eis used to set environment variables. In the example above,MODEis used to set the startup mode of OceanBase Database, andOB_TENANT_PASSWORDis 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 bashView details about the cluster.
# View the list of clusters obd cluster list # View the details of the obcluster cluster obd cluster display obclusterConnect 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.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 through port 2886 of the host machine.
Supported environment variables
Variable |
Default value |
Valid values |
Description |
|---|---|---|---|
| MODE | MINI |
NoteIf |
Set the cluster startup mode. |
| EXIT_WHILE_ERROR | true |
|
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.
NoteWhen |
| 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. |