diff --git a/tools/docker/standalone/README-CN.md b/tools/docker/standalone/README-CN.md index 50b11db6b3..f2ca5f42a1 100644 --- a/tools/docker/standalone/README-CN.md +++ b/tools/docker/standalone/README-CN.md @@ -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/)。 diff --git a/tools/docker/standalone/README.md b/tools/docker/standalone/README.md index 3dfc56d065..e01c7860c3 100644 --- a/tools/docker/standalone/README.md +++ b/tools/docker/standalone/README.md @@ -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/).