Skip to content

Commit

Permalink
update readme of oceanbase-ce (#20)
Browse files Browse the repository at this point in the history 
* update readme of oceanbase-ce

* update readme

* fix CR
  • Loading branch information
@chris-sun-star
chris-sun-star authored Jun 25, 2024
1 parent 7621647 commit 82038e8
Show file tree
Hide file tree
Showing 2 changed files with 46 additions and 104 deletions.
126 changes: 46 additions & 80 deletions oceanbase-ce/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,127 +1,93 @@
# 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 [dockerhub](https://hub.docker.com/r/oceanbase/oceanbase-ce), [quay.io](https://quay.io/repository/oceanbase/oceanbase-ce) and [ghcr.io](https://ghcr.io/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
# Execute init SQL scripts after bootstrap, do not change root user's password in SQL scripts.
# If you'd like to change root user's password, use variable OB_TENANT_PASSWORD.
docker run -p 2881:2881 --name oceanbase-ce -v {init_sql_folder_path}:/root/boot/init.d -d oceanbase/oceanbase-ce

```

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!
```

## 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
docker logs oceanbase-ce | tail -1
```

Or you can run the following command to connect to the OceanBase instance with your local `obclient` or MySQL client directly.
Expected output:
```
boot success!
```

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.
## 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.

```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 |
| OB_TENANT_PASSWORD | | The oceanbase root user password of mysql tenant |
| 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.
24 changes: 0 additions & 24 deletions oceanbase-ce/boot/ob-mysql
View file

This file was deleted.

0 comments on commit 82038e8

Please sign in to comment.