Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update readme of oceanbase-ce #20

Merged
merged 3 commits into from
Jun 25, 2024
Merged

update readme of oceanbase-ce #20

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
00fa71e
update readme of oceanbase-ce
chris-sun-star Jun 25, 2024
0a869d7
update readme
chris-sun-star Jun 25, 2024
ebd3c0d
fix CR
chris-sun-star Jun 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 50 additions & 79 deletions oceanbase-ce/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,127 +1,98 @@
# How to deploy OceanBase with docker
# Deploy OceanBase with Docker

OceanBase provide a standalone test image named [oceanbase-ce](https://hub.docker.com/r/oceanbase/oceanbase-ce) for OceanBase Database. By default, this image deploys a MINI_MODE OceanBase instance.
## Introduction

**WARNING**
The `oceanbase-ce` Docker image, available on [Docker Hub](https://hub.docker.com/r/oceanbase/oceanbase-ce), is designed for users to quickly set up an OceanBase environment for testing purposes.

- The `oceanbase-ce` docker image is just used for study or test;
- Please use [ob-operator](https://github.com/oceanbase/ob-operator) instead if you want to deploy OceanBase on Kubernetes;
- You should not deploy it with important data as it is not designed to use in production environment.
### Key Considerations:
- This image is intended for testing only; do not use it in production environments.
- The image supports the setup of a single-instance cluster only.
- This image is not designed for Kubernetes. For running containerized OceanBase on Kubernetes, refer to the [ob-operator](https://github.com/oceanbase/ob-operator) repository.

Reasons:
## Prerequisites

1. The cluster contains only one instance, so there is no disaster tolerant ability;
2. It is very difficult to recover after failure because docker container cannot be started if the OceanBase instance started failed, which means you may lost the container and the data in it;
3. K8s can not restart a new pod because the container still exists after the observer process quit.
Before deploying `oceanbase-ce`, ensure that the following requirements are met:
- The host machine should have at least 2 physical cores and 8GB of memory.
- Docker should be installed and running on the host machine. Refer to the [Docker installation guide](https://docs.docker.com/get-docker/).

## Prerequisite
## Starting an OceanBase Instance

Before you deploy `oceanbase-ce`, please do the following checks:

- Make sure that your machine has enough resource that can execute at least 2 physical cores and 8GB memory.
- Your machine has installed the latest [Docker](https://docs.docker.com/get-docker/).
- You have started the Docker service on your machine.

## Start an OceanBase instance

To start an OceanBase instance, run this command:
To start an OceanBase instance, use one of the following `docker run` commands:

```bash
# deploy mini instance
# Deploy a mini mode instance
docker run -p 2881:2881 --name oceanbase-ce -d oceanbase/oceanbase-ce

# deploy an instance of the largest size according to the current container
# Deploy an instance to utilize the full resource of the container
docker run -p 2881:2881 --name oceanbase-ce -e MODE=normal -d oceanbase/oceanbase-ce

# deploy a quick-start instance in any mode as desired to the current container
# Deploy an instance using fastboot mode
docker run -p 2881:2881 --name oceanbase-ce -e MODE=slim -d oceanbase/oceanbase-ce

# deploy an instance and execute init sqls
# Deploy an instance and execute init SQL scripts after bootstrap
docker run -p 2881:2881 --name oceanbase-ce -v {init_sql_folder_path}:/root/boot/init.d -d oceanbase/oceanbase-ce
chris-sun-star marked this conversation as resolved.
Show resolved Hide resolved

```

Up to five minutes are necessary for the boot procedure. To make sure that the boot procedure is successful, run this command:
The bootstrap procedure may take up to five minutes. Verify the bootstrap completion by running:

```bash
$ docker logs oceanbase-ce | tail -1
boot success!
```
docker logs oceanbase-ce | tail -1
```

## Connect to an OceanBase instance

The `oceanbase-ce` image contains `obclient` (OceanBase Database Client) and the default connection script `ob-mysql`.

```bash
docker exec -it oceanbase-ce ob-mysql sys # Connect with the root account of sys tenant
docker exec -it oceanbase-ce ob-mysql root # Connect with the root account of a general tenant
docker exec -it oceanbase-ce ob-mysql test # Connect with the test account of a general tenant
Expected output:
```
boot success!
```

Or you can run the following command to connect to the OceanBase instance with your local `obclient` or MySQL client directly.
## Connecting to OceanBase Instance
***Note***:
- Users created in the instance via script use empty passwords by default.
- The default general non-sys tenant is 'test', so 'root@test' is used as the username.

Note:
- The users created by script in the instance uses empty password by default.
- The general non-sys tenant is 'test' by default, so here we use 'root@test' and 'test@test' as usernames.
The oceanbase-ce image includes obclient (OceanBase Database Client) and a default connection script ob-mysql. Use the following commands to connect to the OceanBase cluster:
```
docker exec -it oceanbase-ce ob-mysql sys # Connect with the root account of sys tenant
docker exec -it oceanbase-ce ob-mysql root # Connect with the root account of a general tenant
docker exec -it oceanbase-ce ob-mysql test # Connect with the test account of a general tenant
```

```bash
mysql -h127.0.0.1 -P2881 -uroot # Connect with the root account of sys tenant
For local connections using obclient or mysql client:
```
mysql -h127.0.0.1 -P2881 -uroot # Connect with the root account of sys tenant
mysql -h127.0.0.1 -P2881 -uroot@test # Connect with the root account of a general tenant
mysql -h127.0.0.1 -P2881 -utest@test # Connect with the test account of a general tenant
```

## Supported environment variables

This table shows the supported environment variables of the current oceanbase-ce mirror version:
## Supported Environment Variables
Below is a table of supported environment variables for the image:

| Variable name | Default value | Description |
|-------------------------|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| MODE | {mini, slim, normal} | If it is mini, then the docker use mini mode to deploy OceanBase Database instance, it should be used only for research/study/evaluation. DO NOT use it for production or performance testing. If it is slim, then the container starts in quick start mode. It remove the obagent and ob-configserver. |
| EXIT_WHILE_ERROR | true | Whether quit the container while start observer failed. If start observer failed, you can not explore the logs as the container will exit. But if you set the EXIT_WHILE_ERROR=false, the container will not exit while observer starting fail and you can use docker exec to debug. |
| MODE | {mini, slim, normal} | mini indicates that the container will use the least amount of resource, normal indicates that the container will use as much as possible of the container resource, and slim indicates that the container will only start observer and using fastboot mode. |
| EXIT_WHILE_ERROR | true | Whether quit the container when failed to start observer. if you set EXIT_WHILE_ERROR=false, the container will not exit and you can use log into the container for debugging. |
| OB_CLUSTER_NAME | obcluster | The oceanbase cluster name |
| OB_TENANT_NAME | test | The oceanbase mysql tenant name |
| OB_MEMORY_LIMIT | 6G | The oceanbase cluster memory_limit configuration |
| OB_DATAFILE_SIZE | 5G | The oceanbase cluster datafile_size configuration |
| OB_LOG_DISK_SIZE | 5G | The oceanbase cluster log_disk_size configuration |
| OB_SYS_PASSWORD | | The oceanbase root user password of sys tenant |
| OB_SYS_PASSWORD | | The oceanbase root user password of sys tenant |
chris-sun-star marked this conversation as resolved.
Show resolved Hide resolved
| OB_SYSTEM_MEMORY | 1G | The oceanbase cluster system_memory configuration |
| OB_TENANT_MINI_CPU | | The oceanbase tenant mini_cpu configuration |
| OB_TENANT_MEMORY_SIZE | | The oceanbase tenant memory_size configuration |
| OB_TENANT_LOG_DISK_SIZE | | The oceanbase tenant log_disk_size configuration |

## Run the Sysbench script

`oceanbase-ce` image installs the Sysbench tool by default. And the Sysbench tool is configured. You can run these commands in sequence to run the Sysbench script with the default configurations.

```bash
## Running Sysbench Script
The oceanbase-ce image includes the sysbench tool for benchmarking. Use the following command to run a sysbench test:
```
docker exec -it oceanbase-ce obd test sysbench obcluster
```

## Mount Volume

You can use `-v /your/host/path:/container/path` parameter in docker `run` command to save data in host os if you want to persistence the data of a container.
## Data Persistence
By default, oceanbase-ce deploys OceanBase under /root/ob and saves its configurations under /root/.obd/cluster. Use the following command to persist data on the host:

Below is an example.

```bash
```
mkdir -p ob
mkdir -p obd/cluster
docker run -d -p 2881:2881 -v $PWD/ob:/root/ob -v $PWD/obd/cluster:/root/.obd/cluster --name oceanbase oceanbase/oceanbase-ce
```

Note that you should use your own path.

The docker image `oceanbase-ce` saves the data to /root/ob directory default. You should bind both the /root/ob and /root/.obd/cluster. You can not start new docker image if you only bind the /root/ob directory, because the docker image `oceanbase-ce` uses the [obd](https://github.com/oceanbase/obdeploy) to manage database clusters and there is no information about the database cluster in a new docker container.

You can view more information about `docker -v` at [docker volume](https://docs.docker.com/storage/volumes/).

## Fault Diagnosis

A series of diagnostic methods are provided to diagnose errors in Docker.

### Support for 'enable_rich_error_msg' parameter

- Initially, the 'enable_rich_error_msg' parameter is enabled by default during the Docker startup process. If an error occurs during the startup process, more error information can be obtained using the trace command. After a successful startup, Docker sets this parameter to the false state.
- Users can open this parameter to obtain more error information about SQL statements during the runtime phase. To open it is, you should connect to the system tenant of OceanBase instance, and then execute the following command:

```sql
alter system set enable_rich_error_msg = true;
```
The enable_rich_error_msg parameter is enabled by default during Docker startup. If an error occurs, you can obtain detailed error information using the trace command.