Stop ODC of the earlier version
When you upgrade OceanBase Developer Center (ODC) deployed in high-availability mode, you must first stop ODC of the earlier version on each node after you back up the MetaDB.
Run the
docker ps -acommand in the command-line tool of the host to view the running containers.You can find the container ID of the earlier image in the
CONTAINER IDcolumn based on the image name in theIMAGEcolumn. The result is as follows:C:\Users\ob>docker ps -a CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 8bfecbc1cd03 acs-reg.alipay.com/oceanbase/obodc:2.0.1 "/bin/sh -c '/usr/bi..." 13 days ago Up 13 days 80/tcp, 8080/tcp, x.x.x.x:8989->8989/tcp obodcAfter you obtain the container ID, run the
docker stop <CONTAINER ID>;command in the command-line tool to stop the ODC container of the earlier version.The result is as follows:
C:\Users\ob>docker stop 8bfecbc1cd03 8bfecbc1cd03Run the
docker rm <CONTAINER ID>;command in the command-line tool to delete the ODC image of the earlier version and release the port occupied.The result is as follows:
C:\Users\ob>docker rm 8bfecbc1cd03 8bfecbc1cd03
Back up the MetaDB
Notice
Before you upgrade ODC, back up the MetaDB. When the upgrade fails, you can roll back ODC by using the backup of MetaDB.
Example: Create ~/odcmetadb_backup as the backup path for the MetaDB and back up the MetaDB of ODC.
#create backup directory
mkdir -p ~/odcmetadb_backup
#backup odc metadb
./obdumper --thread 1 -h <host> -P <port> -u <username> -c <cluster_name> -t <tenant_name> -D <database_name> --ddl --csv --no-sys --all -f ~/odcmetadb_backup
Note
For information about backup options, see Command-line options of OBDUMPER.
Load and run an ODC image
When you upgrade ODC deployed in high availability mode, you need to obtain and run the ODC image again on each node after you update the MetaDB.
Load the image
Notice
- Images of ODC V4.2.0 and later have been released in Docker Hub. If the server where ODC runs can access Docker Hub, you do not need to download an image and can directly start ODC Docker. For more information, see the "Run the image" section in this topic.
- If the server where ODC runs cannot access Docker Hub, you need to download and load the image file.
To obtain the ODC image on the host, select the required image from the Maintenance Tools of the OceanBase Download Center.
After you obtain the image, run the following command in the command-line tool to load it:
gunzip -c obodc-{$version}.tar.gz | docker load
Run the image
Run a command in the command-line tool on the host to run the obtained ODC image. The sample command is as follows:
#!/usr/bin/env bash
docker run -v /var/log/odc:/opt/odc/log -v /var/data/odc:/opt/odc/data \
-d -i --net host --cpu-period 100000 --cpu-quota 400000 --memory 8G --name "obodc" \
-e "DATABASE_HOST=xxx.xx.xx.xx" \
-e "DATABASE_PORT=60805" \
-e "DATABASE_USERNAME=[username]@[tenant name]#[cluster name]" \
-e "DATABASE_PASSWORD=******" \
-e "DATABASE_NAME=odc_metadb" \
-e "ODC_PROFILE_MODE=alipay" \
-e "ODC_ADMIN_INITIAL_PASSWORD=******" \
oceanbase/odc:4.2.2
Notice
In the Shell environment, you must enclose a string that contains special characters such as ! and $ with single quotation marks ('), for example, DATABASE_PASSWORD='11111!'.
The following table describes the parameters.
| Parameter | Description |
|---|---|
| -v |
|
| --net | The network configuration of the Docker container. If you set this parameter to host, the host network is directly used. You can also use the --publish (-p) parameter to configure port mapping. However, the Docker container may fail to start in some environments due to internal DNS resolution errors. In this case, specify --net host in the command to start the Docker container. |
| --cpu-period --cpu-quota | ---cpu-period parameter specifies the interval at which the CPU cores of the Docker container are reallocated. Unit: μs.---cpu-quota parameter specifies the maximum time for running the current Docker container in this interval. Unit: μs.cpu-quota by cpu-period. In the preceding sample statement, the values of cpu-quota and cpu-period are respectively 400000 and 100000. Therefore, the resulting value is 4, indicating that the Docker container can use at most four CPU cores. |
| --memory | The maximum memory size for the Docker container. |
| --name | The name of the container. |
| DATABASE_HOST | The IP address of the MetaDB. |
| DATABASE_PORT | The port number of the MetaDB. |
| DATABASE_USERNAME | The username of the MetaDB. In OceanBase Database, the username is in the format of db_user@tenant_name#cluster_name. |
| DATABASE_PASSWORD | The password used to connect to the database. |
| DATABASE_NAME | The name of the MetaDB. |
| ODC_PROFILE_MODE | The profile mode. Default value: alipay. |
| ODC_ADMIN_INITIAL_PASSWORD | The initial password of the administrator account of ODC.
NoticeThe initial password must meet the following requirements:
|
In addition to the preceding parameters, you can also use the following parameters when running the image.
| Parameter | Description |
|---|---|
| ODC_LOG_DIR | The log directory. Default value: /opt/odc/log. |
| ODC_JVM_HEAP_OPTIONS | The JVM heap size configurations. Default value: -XX:MaxRAMPercentage=60.0 -XX:InitialRAMPercentage=60.0, indicating that the JVM heap size is 60% of the total memory. You can also directly specify the JVM heap size by setting the ODC_JVM_HEAP_OPTIONS parameter. For example, -Xmx2048m -Xms2048m indicates that the heap size is 2 GB. |
| ODC_JVM_GC_OPTIONS | The garbage collection strategy for JVM. Default value: -XX:+UseG1GC -XX:+PrintAdaptiveSizePolicy -XX:+PrintGCDetails -XX:+PrintGCTimeStamps -XX:+PrintGCDateStamps -Xloggc:/opt/odc/log/gc.log -XX:+UseGCLogFileRotation -XX:GCLogFileSize=50M -XX:NumberOfGCLogFiles=5. |
| ODC_JVM_OOM_OPTIONS | The OutOfMemory strategy for JVM. Default value: -XX:+ExitOnOutOfMemoryError. |
| ODC_JVM_EXTRA_OPTIONS | Other JVM parameters. By default, no other parameter is specified. |
| ODC_SERVER_PORT | The HTTP listening port for ODC-Server. Default value: 8989. |
| ODC_HOST | The IP address of ODC, which can be used as the destination IP address for remote procedure calls in high-availability deployment scenarios. |
| ODC_MAPPING_PORT | The port number of ODC, which is specified to avoid port unavailability due to the deployment environment. This parameter is applicable to port mapping when ODC is deployed in Docker. |
| ODC_APP_EXTRA_ARGS | Other app parameters. For example, --server.servlet.session.timeout=10m indicates that the session timeout period is 10 minutes. By default, no other parameter is specified. |
Upgrade Nginx image
When you upgrade Web ODC, you can choose whether to upgrade the Nginx image to the latest version. To upgrade the Nginx image, you must stop and delete the old image, obtain the image of the latest version on the host, and deploy the Nginx proxy.
Stop and delete the old image
Before you deploy the Nginx image of the latest version, you must stop and delete the Nginx image that is running on the host.
Run the
docker ps -acommand in the command-line tool of the host to view the running containers.You can find the container ID of the earlier Nginx image in the
CONTAINER IDcolumn based on the image name in theIMAGEcolumn. The result is as follows:" C:\Users\ob>docker ps -a CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 8bfecbc1cd03 bdd6f8916e8b "/bin/sh -c '/usr/bi... 13 days ago Up 13 days 80/tcp, 8080/tcp, x.x.x.x:8989->8989/tcp nginxAfter you obtain the container ID, run the
docker stop <CONTAINER ID>;command in the command-line tool to stop the ODC container of the earlier version.The result is as follows:
C:\Users\ob>docker stop 8bfecbc1cd03 8bfecbc1cd03Run the
docker rm <CONTAINER ID>;command in the command-line tool to delete the ODC image of the earlier version and release the port occupied.The result is as follows:
C:\Users\ob>docker rm 8bfecbc1cd03 8bfecbc1cd03
Load the new image
You can use the following methods to load the Nginx image of the latest version:
Pull the image from the Docker warehouse on the host.
Download the image package to a local device, copy the package to the host, and decompress the package.
Pull the image from the Docker warehouse
Ensure that Docker is installed on the host and the host has access to the Internet. Then, run the following command in the command-line tool to pull the Nginx image from the Docker warehouse:
docker pull nginx
Copy the image package to the host and decompress the package
Ensure that Docker is installed on the host and the host has access to the Internet. Then, run the following command on the host to download the image package to a local device:
docker save nginx:latest | gzip - >nginx.tar.gz
Copy the image package to the host and run the following command to load the image:
gunzip -c nginx.tar.gz | docker load
Configure the configuration file
Before you start running the Nginx image, you must modify settings of the configuration file. The ODC image package contains templates of the configuration file. You can copy a template to a local device and edit the configuration where necessary. The templates of the configuration file vary, depending on whether you have deployed a self-signed certificate. We recommend that you copy a template based on the deployment and modify the configuration where necessary.
Configure the configuration file that does not contain the self-signed certificate
Run the following command to copy the configuration file from the image package to a custom path on the host for editing. The tilde (~) indicates the local path where the configuration file is located.
docker cp -a <odc_image_name>:/opt/odc/conf/nginx.conf.template ~/<conf_local_path>
The following code shows a template of the configuration file. We recommend that you modify the settings based on the comments.
# Nginx conf template for http deployment
# For more information on configuration, see:
# * Official English Documentation: http://nginx.org/en/docs/
user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log;
pid /run/nginx.pid;
# Load dynamic modules. See /usr/share/doc/nginx/README.dynamic.
include /usr/share/nginx/modules/*.conf;
events {
worker_connections 1024;
}
http {
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';
access_log /var/log/nginx/access.log main;
sendfile on;
tcp_nopush on;
tcp_nodelay on;
keepalive_timeout 65;
types_hash_max_size 2048;
#set 0 to disable request body size check, for support large size file upload
client_max_body_size 0;
include /etc/nginx/mime.types;
default_type application/octet-stream;
# for websocket configuration
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
# load balancing configuration
# notice under_score character are not allowed for upsteram name, 400 Bad Request happens if used
# please use ip_hash strategy
# one server line for each odc-server node
upstream odcbackends {
ip_hash;
# Change it to the actual ODC server address. This operation is optional.
server xxx.x.x.x:8989;
# add more servers here
}
#https server, proxy to odc-server 8989 port
server {
listen 80;
# uncomment below if ipv6 enabled
# If IPv6 is enabled, you must uncomment the following content:
#listen [::]:80;
# Change it to the actual domain name of the site. This operation is optional.
server_name odc.oceanbase.com;
location / {
proxy_pass http://odcbackends;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 1800;
proxy_send_timeout 1800;
proxy_connect_timeout 75;
proxy_next_upstream off;
}
}
}
Configure the configuration file that contains a self-signed certificate
Run the following command to copy the configuration file from the image package to a custom path on the host for editing. The tilde (~) indicates the local path where the configuration file is located.
docker cp -a <odc_image_name>:/opt/odc/conf/nginx.conf.https.template ~/<conf_local_path>
The following code shows a template of the configuration file. We recommend that you modify the settings based on the comments.
# Nginx conf template for https deployment
# For more information on configuration, see:
# * Official English Documentation: http://nginx.org/en/docs/
user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log;
pid /run/nginx.pid;
# Load dynamic modules. See /usr/share/doc/nginx/README.dynamic.
include /usr/share/nginx/modules/*.conf;
events {
worker_connections 1024;
}
http {
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';
access_log /var/log/nginx/access.log main;
sendfile on;
tcp_nopush on;
tcp_nodelay on;
keepalive_timeout 65;
types_hash_max_size 2048;
#set 0 to disable request body size check, for support large size file upload
client_max_body_size 0;
include /etc/nginx/mime.types;
default_type application/octet-stream;
# for websocket configuration
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
# load balancing configuration
# notice under_score character are not allowed for upsteram name, 400 Bad Request happens if used
# please use ip_hash strategy
# one server line for each odc-server node
upstream odcbackends {
ip_hash;
# PLEASE CHANGE to real odc-server address
# Change it to the actual ODC server address. This operation is optional.
server xxx.x.x.x:8989;
#add more servers here
}
# redirect http to https
server {
listen 80 default_server;
# uncomment below if ipv6 enabled
# If IPv6 is enabled, you must uncomment the following content:
#listen [::]:80 default_server;
location / {
return 301 https://$host$request_uri;
}
}
# https server, proxy to odc-server 8989 port
server {
listen 443 ssl http2;
# uncomment below if ipv6 enabled
# If IPv6 is enabled, you must uncomment the following content:
#listen [::]:443 ssl http2;
# PLEASE CHANGE to your site domain
# Change it to the actual domain name of the site. This operation is optional.
server_name odc.oceanbase.com;
# you can use /opt/odc/bin/generate-odc-ssl-certificate.sh
# to generate self certificated SSL certificates
# You can use /opt/odc/bin/generate-odc-ssl-certificate.sh to generate a self-signed certificate.
# PLEASE CHANGE certificate file location if unmatched
# Change the path of the certificate file in the case of a mismatch.
ssl_certificate /etc/pki/nginx/odcserver.crt;
ssl_certificate_key /etc/pki/nginx/odcserver.key;
ssl_session_timeout 1d;
ssl_session_cache shared:MozSSL:10m; # about 40000 sessions
ssl_session_tickets off;
# intermediate configuration
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off;
# HSTS (ngx_http_headers_module is required) (63072000 seconds)
add_header Strict-Transport-Security "max-age=63072000" always;
location / {
proxy_pass http://odcbackends;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 1800;
proxy_send_timeout 1800;
proxy_connect_timeout 75;
proxy_next_upstream off;
}
}
}
Note
- You can modify the load balancing configurations to ensure sufficient proxy server timeout. The modification takes effect after you restart the Nginx proxy. We recommend that you set the
proxy_connect_timeoutparameter to a value not longer than 75 seconds. For more information, see proxy_connect_timeout. - If you do not set the
proxy_next_upstreamparameter tooff, the Nginx proxy will forward your requests to the next ODC node. In this case, you need to log on to ODC again, and cannot use features related to file upload and download, such as downloading the result set of an asynchronous task.
Start the image
After the configuration file is modified locally, run the following command in the command-line tool to restart the Nginx image. The tilde (~) indicates the local path where the configuration file is located.
docker run --network host --name nginx -v ～/<conf_local_path>:/etc/nginx/nginx.conf -v /etc/pki/nginx/:/etc/pki/nginx/ -d nginx
The following table describes the parameters in the command.
| Parameter | Description |
|---|---|
| --network host | Specifies to use a network port of the host. You do not need to configure port mapping in this case. If you do not want to directly use the port of the host, you can specify the mapping ports using the -p parameter. For example, -p 8080:80 specifies to map port 8080 of the host to port 80 of the Docker container. Likewise, -p 8443:443 specifies to map port 8443 of the host to port 443 of the Docker container. |
| --name nginx | Sets the name of the container to nginx for easier management. You can use other names, for example, odc-nginx. |
| -v ~/<conf_local_path>:/etc/nginx/nginx.conf | Mounts the Docker container to the specified directory of the host and maps the local files of the host to the Docker container. <conf_local_path> specifies a local path of the configuration file on the host, and then maps the configuration file to the /etc/nginx/nginx.conf file in the Docker container. |
| -v /etc/pki/nginx/:/etc/pki/nginx/ | Maps the /etc/pki/nginx/ path of the host to the /etc/pki/nginx/ path of the Docker container. |
| -d nginx | Specifies to run the Docker container in the background. |