hcq/oceanbase
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

update docker doc

Browse Source
This commit is contained in:
hnwyllmm
2023-01-11 05:08:11 +00:00
committed by ob-robot
parent 975047edcb
commit 1a6f43281b
2 changed files with 77 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
tools/docker/standalone/README-CN.md
View File

@ -1,10 +1,22 @@
# 如何使用这个镜像
# 如何使用Docker部署OceanBase
部署 OceanBase 数据库的方式有很多，使用 Docker 是其中较方便的一种。本仓库提供了 OceanBase 数据库的 Docker 镜像 oceanbase-standalone。oceanbase-standalone 是 OceanBase 数据库的单机镜像。默认会根据当前容器情况部署最大规格的实例，也可以通过环境变量指定MINI MODE部署最小规格实例。
OceanBase 提供了一个独立部署的测试镜像[oceanbase-ce](https://hub.docker.com/r/oceanbase/oceanbase-ce)。默认情况下，这个镜像会在当前容器环境中部署一个占用最大资源的数据库实例。不过可以使用环境变量MINI_MODE来部署一个mini模式的数据库实例。
## 前提条件
**注意**
在部署 oceanbase-standalone 镜像之前，您需要确认以下信息：
- oceanbase-ce docker镜像仅能用做学习研究或测试使用；
- 如果想要在k8s中部署oceanbase，请使用[oceanbase-operator](https://github.com/oceanbase/ob-operator)；
- 千万不要使用此镜像用于带有重要数据的场景，比如生产环境。
理由：
1. 这个集群仅包含一个实例，所以没有容灾能力；
2. 因为oceanbase实例出现异常无法正常启动时，docker容器也无法启动，所以在异常时难以恢复，这意味着对应的容器(container)就没用了。如果没有使用docker volume 将数据目录挂载到其它地方，那么容器中的数据也丢失了；
3. observer进程退出的时候，对应的容器不会退出，所以k8s也没有机会去启动一个新的pod。
## 前置条件
在部署 oceanbase-ce 镜像之前，您需要确认以下信息：
- 确保您的机器至少提供 2 核 10GB 以上的资源。
- 您的机器已经安装以下程序：
@ -20,85 +32,66 @@
```bash
# 根据当前容器情况部署最大规格的实例
docker run -p 2881:2881 --name obstandalone -d oceanbase/oceanbase-ce-standalone
docker run -p 2881:2881 --name oceanbase-ce -d oceanbase/oceanbase-ce
# 部署最小规格实例
docker run -p 2881:2881 --name obstandalone -e MINI_MODE=1 -d oceanbase/oceanbase-ce-standalone
docker run -p 2881:2881 --name oceanbase-ce -e MINI_MODE=1 -d oceanbase/oceanbase-ce
```
启动预计需要 2-5 分钟。执行以下命令，如果返回 `boot success!`，则启动成功。
```bash
$ docker logs obstandalone | tail -1
$ docker logs oceanbase-ce | tail -1
boot success!
```
**WARNING:** 如果observer进程出现异常退出，容器不会自动退出。
**注意：** 如果observer进程出现异常退出，容器不会自动退出。
## 连接 OceanBase 实例
oceanbase-standalone 镜像安装了 OceanBase 数据库客户端 obclient，并提供了默认连接脚本 ob-mysql。
oceanbase-ce 镜像安装了 OceanBase 数据库客户端 obclient，并提供了默认连接脚本 `ob-mysql`。
```bash
docker exec -it obstandalone ob-mysql sys # 连接 sys 租户
docker exec -it obstandalone ob-mysql root # 连接用户租户的 root 账户
docker exec -it obstandalone ob-mysql test # 连接用户租户的 test 账户
docker exec -it oceanbase-ce ob-mysql sys # 连接 sys 租户
docker exec -it oceanbase-ce ob-mysql root # 连接用户租户的 root 账户
docker exec -it oceanbase-ce ob-mysql test # 连接用户租户的 test 账户
```
您也可以运行以下命令，使用您本机的 obclient 或者 MySQL 客户端连接实例。
```bash
$mysql -uroot -h127.1 -P2881
```
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 167310
Server version: 5.7.25 OceanBase 3.1.0 (r-00672c3c730c3df6eef3b359eae548d8c2db5ea2) (Built Jun 22 2021 12:46:28)
Copyright (c) 2000, 2021, Oracle and/or its affiliates.
Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
mysql>
mysql -uroot -h127.1 -P2881
```
## 支持的环境变量
下表列出了当前版本的 oceanbase-standalone 镜像支持的环境变量：
变量名称 | 默认值 | 描述
------- | ----- | ---
MINI_MODE | false | OceanBase 数据库实例是否采用mini模式部署，该模式仅供研究、学习和评估使用，不适用于生产环境或性能测试场景。
EXIT_WHILE_ERROR | true | OceanBase 如果启动失败，是否退出容器。比如初次run镜像失败，或start容器失败，可以将此参数设置为false,那么OB启动失败，也可以进入容器，查看OceanBase的运行日志，然后进行排查。
OB_HOME_PATH | /root/ob | OceanBase 数据库实例的部署路径。
OB_DATA_DIR | empty | OceanBase 数据库使用的数据存储路径。默认在部署路径下的 `store` 目录
OB_REDO_DIR | empty | OceanBase 数据库使用的clog，ilog，slog路径。默认与数据存储路径一致。
OB_MYSQL_PORT | 2881 | OceanBase 数据库实例的 MySQL 协议端口。
OB_RPC_PORT | 2882 | OceanBase 数据库实例的 RPC 通信端口。
OB_ROOT_PASSWORD | empty | OceanBase 数据库实例 sys 租户的密码。
OB_CLUSTER_NAME | obcluster | OceanBase 数据库实例名称，OBD 将使用这个名称作为集群名。
OB_TENANT_NAME | test | OceanBase 数据库实例默认初始化的用户租户的名称。
下表列出了当前版本的 oceanbase-ce 镜像支持的环境变量。
| 变量名称 | 默认值 | 描述 |
| ---------------- | ------------- | ------------------------------------------------------------ |
| MINI_MODE | true | true表示使用mini 模式部署OceanBase数据库实例，仅用来研究学习使用。不适合用于生产或性能测试。 |
| EXIT_WHILE_ERROR | true | OceanBase 如果启动失败，是否退出容器。比如初次run镜像失败，或start容器失败，可以将此参数设置为false,那么OB启动失败，也可以进入容器，查看OceanBase的运行日志，然后进行排查。 |
## 运行 Sysbench 脚本
oceanbase-ce 镜像默认安装了 Sysbench 工具，并进行了简单配置。您可以依次执行以下命令，使用默认配置运行 Sysbench 脚本。
```bash
docker exec -it obstandalone obd test sysbench [OB_CLUSTER_NAME]
docker exec -it oceanbase-ce obd test sysbench obcluster
```
## 磁盘挂载
## Mount Volumn
如果想要将容器中的数据持久化保存下来，通常的做法是在`run` docker镜像时，使用 `-v /host/path:/container/path` 的方式将数据保存在宿主机上。
oceanbase-ce镜像的数据库数据默认保存在/root/ob目录下。但是仅仅映射/root/ob目录，会导致新的镜像无法启动，因为oceanbase-ce镜像是使用[obd](https://github.com/oceanbase/obdeploy) 来管理集群的，新的镜像启动时，没有oceanbase的集群信息，所以需要同时挂载/root/ob和/root/.obd目录。
挂载目录运行示例：
```bash
docker run -d -p 2881:2881 -v $PWD/ob:/root/ob -v $PWD/obd:/root/.obd --name oceanbase oceanbase/oceanbase-ce
docker run -d -p 2881:2881 -v $PWD/ob:/root/ob -v $PWD/obd:/root/.obd --name oceanbase-ce oceanbase/oceanbase-ce
```
注意需要按照实际情况调整自己的目录。
docker -v 参数的详细说明可以参考 [docker volumn](https://docs.docker.com/storage/volumes/)
`oceanbase-ce` docker默认会将数据保存到 /root/ob 目录。必须同时绑定 /root/ob 和 /root/.obd 目录。如果仅仅绑定 /root/ob 目录的话，容器就没办法重启了，因为oceanbase-ce 是使用 [obd](https://github.com/oceanbase/obdeploy)来管理数据库集群的，而启动一个全新的docker容器时，里面没有任何数据库集群信息。
docker -v 参数的详细说明可以参考 [docker volumn](https://docs.docker.com/storage/volumes/)。

89
tools/docker/standalone/README.md
View File

@ -1,17 +1,29 @@
# How to use this image
# How to deploy OceanBase with docker
You can deploy OceanBase databases by using many methods. But Docker is the easiest method. This repository gives you an oceanbase-standalone image for deploying OceanBase database by using Docker. oceanbase-standalone is a standalone test image for OceanBase Database. By default, this image deploys an instance of the largest size according to the current container. You can also deploy a mini standalone instance through the environment variable MINI_MODE.
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.
**WARNING**
- The oceanbase-ce docker image is just used for study or test;
- Please use [oceanbase-operator](https://github.com/oceanbase/ob-operator) instead if you want to deploy oceanbase in k8s;
- You should not deploy it with important data as it is not used in production environment.
Reasons:
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 started while the oceanbase instance cannot start success, which means you lost the container and the data with it;
3. K8s can not restart a new pod because the container still exists after the observer process quit.
## Prerequisite
Before you deploy oceanbase-standalone image, do a check of these:
Before you deploy oceanbase-ce docker, do the following checks:
- Make sure that your machine has at least 2 physical core and 10GB memory.
- Make sure that your machine has enough resource that can execute at least 2 phycical core and 8GB memory.
- Your machine has installed these applications:
Application | Recommended version | Documentation
--- | ------ | -----
Docker | Latest | [Docker Documentation](https://docs.docker.com/get-docker/)
| Application | Recommended version | Documentation |
| ----------- | ------------------- | ----------------------------------------------------------- |
| Docker | Latest | [Docker Documentation](https://docs.docker.com/get-docker/) |
- You have started the Docker service on your machine.
## Start an OceanBase instance
@ -19,80 +31,55 @@ Before you deploy oceanbase-standalone image, do a check of these:
To start an OceanBase instance, run this command:
```bash
# deploy an instance of the largest size according to the current container
docker run -p 2881:2881 --name obstandalone -d oceanbase/oceanbase-ce-standalone
# deploy mini instance
docker run -p 2881:2881 --name oceanbase-ce -d oceanbase/oceanbase-ce
# deploy mini standalone instance
docker run -p 2881:2881 --name obstandalone -e MINI_MODE=1 -d oceanbase/oceanbase-ce-standalone
# deploy an instance of the largest size according to the current container
docker run -p 2881:2881 --name oceanbase-ce -e MINI_MODE=0 -d oceanbase/oceanbase-ce
```
Two to five minutes are necessary for the boot procedure. To make sure that the boot procedure is successful, run this command:
```bash
$ docker logs obstandalone | tail -1
$ docker logs oceanbase-ce | tail -1
boot success!
```
**WARNING:** the container will not exit while the process of observer exits.
## Connect to an OceanBase instance
oceanbase-standalone image contains obclient (OceanBase Database client) and the default connection script `ob-mysql`.
oceanbase-ce image contains obclient (OceanBase Database client) and the default connection script `ob-mysql`.
```bash
docker exec -it obstandalone ob-mysql sys # Connect to sys tenant
docker exec -it obstandalone ob-mysql root # Connect to the root account of a general tenant
docker exec -it obstandalone ob-mysql test # Connect to the test account of a general tenant
docker exec -it oceanbase-ce ob-mysql sys # Connect to sys tenant
docker exec -it oceanbase-ce ob-mysql root # Connect to the root account of a general tenant
docker exec -it oceanbase-ce ob-mysql test # Connect to the test account of a general tenant
```
Or you can run this command to connect to an OceanBase instance with your local obclient or MySQL client.
```bash
$mysql -uroot -h127.1 -P2881
```
When you connect to an OceanBase instance successfully, the terminal returns this message:
```mysql
Welcome to the MariaDB monitor. Commands end with ; or \g.
Your MySQL connection id is 3221528373
Server version: 5.7.25 OceanBase 2.2.77 (r20211015104618-3510dfdb38c6b8d9c7e27747f82ccae4c8d560ee) (Built Oct 15 2021 11:19:05)
Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
MySQL [(none)]>
mysql -uroot -h127.1 -P2881
```
## Supported environment variables
This table shows the supported environment variables of the current oceanbase-standalone mirror version:
This table shows the supported environment variables of the current oceanbase-ce mirror version:
Variable name | Default value | Description
------- | ----- | ---
MINI_MODE | false | If ture, will 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.
OB_HOME_PATH | /root/ob | Home path for an OceanBase Database instance.
OB_MYSQL_PORT | 2881 | The MySQL protocol port for an OceanBase Database instance.
OB_DATA_DIR | empty | The directory for data storage. The default value is $OB_HOME_PATH/store.
OB_REDO_DIR | empty | The directory for clog, ilog, and slog. The default value is the same as the OB_DATA_DIR value.
OB_RPC_PORT | 2882 | The RPC communication port for an OceanBase Database instance.
OB_ROOT_PASSWORD | empty | The password for the system tenant in an OceanBase Database instance.
OB_CLUSTER_NAME | mini-ce | Instance name for OceanBase Database instance. OBD uses this value as its cluster name.
OB_TENANT_NAME | test | The default initialized general tenant name for an OceanBase Database instance.
| Variable name | Default value | Description |
| ---------------- | ------------- | ------------------------------------------------------------ |
| MINI_MODE | false | If ture, will 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. |
| 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. |
## Run the Sysbench script
oceanbase-standalone 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.
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
docker exec -it obstandalone obd test sysbench [OB_CLUSTER_NAME]
docker exec -it oceanbase-ce obd test sysbench obcluster
```
## Mount Volumn
You can use `-v /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.
The docker image `oceanbase-ce` save the data to /root/ob directory default. You can not start a new docker image if you only bind the /root/ob directory, because the docker image oceanbase-ce use the [obd](https://github.com/oceanbase/obdeploy) to manage database clusters and there is no information about the database cluster after a new docker image started. So you should bind both the /root/ob and /root/.obd directory.
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.
Below is an example.
@ -102,4 +89,6 @@ docker run -d -p 2881:2881 -v $PWD/ob:/root/ob -v $PWD/obd:/root/.obd --name oce
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. 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 volumn](https://docs.docker.com/storage/volumes/).