Deploy OceanBase Database in a container

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

Prerequisites

Before you perform the operations in this topic, 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 machines, only Docker V4.9.0 and earlier are supported for deploying OceanBase Database. You can click here to download Docker.

• 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 OceanBase Database images

  [admin@test001 ~]$ sudo docker search oceanbase
  

• Pull the latest OceanBase Database image

  [admin@test001 ~]$ sudo docker pull oceanbase/oceanbase-ce
  

  Note

  • If the Docker image pull fails, you can also pull the image from the quay.io or ghcr.io repositories. Just replace oceanbase/oceanbase-ce in the pull command with quay.io/oceanbase/oceanbase-ce or ghcr.io/oceanbase/oceanbase-ce, for example, execute sudo docker pull quay.io/oceanbase/oceanbase-ce to pull the image from quay.io.

  • If you change the repository address in the command of this step, you also need to change the repository address in the command of Step 2. The two commands must use the same repository.

  • The above commands default to pulling the latest version. You can choose a version from dockerhub, quay.io, or ghcr.io based on your needs.

Step 2: Start an OceanBase Database instance

Run the following commands 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

The options in the example are described as follows:

• -p maps the container's ports to the host's ports. In the example, it maps container ports 2881 and 2886 to host ports 2881 and 2886.

• -v shares files or directories between the container and the host, enabling data persistence or configuration sharing. By default, the system deploys OceanBase Database in the /root/ob directory of the container and saves its configuration in /root/.obd/cluster. You can use this option to persist data on the host.

  You can also use the -v option to mount an SQL script for execution. Here's an example. You need to replace {init_sql_folder_path} with the actual path to 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
  

• --name sets the Docker container name. For example, the example creates a Docker container named obstandalone.

• -e sets environment variables. In the example, MODE sets the startup mode for OceanBase Database, and OB_TENANT_PASSWORD sets the password for the root@test user in OceanBase Database. For more information about the environment variables, see Supported environment variables below.

Starting an instance takes about 2 to 5 minutes. 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 obd commands or the OBClient client to manage and connect to the instance. Alternatively, you can use the OBClient or MySQL client on the host to connect to the OceanBase Database instance.

Connect to the instance after entering the container

1. Enter the Docker container.

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

2. View the cluster details.

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

3. Connect to the cluster.

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

Connect to the instance using the host's client

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

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

After a successful connection, 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

You can access the obshell Dashboard, a web-based management interface provided by obshell, by visiting port 2886 on the host.

Supported environment variables