OceanBase logo

OceanBase

A unified distributed database ready for your transactional, analytical, and AI workloads.

Product Overview
DEPLOY YOUR WAY

OceanBase Cloud

The best way to deploy and scale OceanBase

OceanBase Enterprise

Run and manage OceanBase on your infra

TRY OPEN SOURCE

OceanBase Community Edition

The free, open-source distributed database

OceanBase seekdb

Open source AI native search database

Customer Stories

Real-world success stories from enterprises across diverse industries.

View All
BY USE CASES

Mission-Critical Transactions

Global & Multicloud Application

Elastic Scaling for Peak Traffic

Real-time Analytics

Active Geo-redundancy

Database Consolidation

Resources

Comprehensive knowledge hub for OceanBase.

Blog

Live Demos

Training & Certification

Documentation

Official technical guides, tutorials, API references, and manuals for all OceanBase products.

View All
PRODUCTS

OceanBase Cloud

OceanBase Database

Tools

Connectors and Middleware

QUICK START

OceanBase Cloud

OceanBase Database

BEST PRACTICES

Practical guides for utilizing OceanBase more effectively and conveniently

Company

Learn more about OceanBase – our company, partnerships, and trust and security initiatives.

About OceanBase

Partner

Trust Center

Contact Us

International - English
中国站 - 简体中文
日本 - 日本語
Sign In
Start on Cloud

OceanBase

A unified distributed database ready for your transactional, analytical, and AI workloads.

Product Overview
DEPLOY YOUR WAY

OceanBase Cloud

The best way to deploy and scale OceanBase

OceanBase Enterprise

Run and manage OceanBase on your infra

TRY OPEN SOURCE

OceanBase Community Edition

The free, open-source distributed database

OceanBase seekdb

Open source AI native search database

Customer Stories

Real-world success stories from enterprises across diverse industries.

View All
BY USE CASES

Mission-Critical Transactions

Global & Multicloud Application

Elastic Scaling for Peak Traffic

Real-time Analytics

Active Geo-redundancy

Database Consolidation

Comprehensive knowledge hub for OceanBase.

Blog

Live Demos

Training & Certification

Documentation

Official technical guides, tutorials, API references, and manuals for all OceanBase products.

View All
PRODUCTS
OceanBase CloudOceanBase Database
ToolsConnectors and Middleware
QUICK START
OceanBase CloudOceanBase Database
BEST PRACTICES

Practical guides for utilizing OceanBase more effectively and conveniently

Learn more about OceanBase – our company, partnerships, and trust and security initiatives.

About OceanBase

Partner

Trust Center

Contact Us

Start on Cloud
编组
All Products
    • Databases
    • iconOceanBase Database
    • iconOceanBase Cloud
    • iconOceanBase Tugraph
    • iconInteractive Tutorials
    • iconOceanBase Best Practices
    • Tools
    • iconOceanBase Cloud Platform
    • iconOceanBase Migration Service
    • iconOceanBase Developer Center
    • iconOceanBase Migration Assessment
    • iconOceanBase Admin Tool
    • iconOceanBase Loader and Dumper
    • iconOceanBase Deployer
    • iconKubernetes operator for OceanBase
    • iconOceanBase Diagnostic Tool
    • iconOceanBase Binlog Service
    • Connectors and Middleware
    • iconOceanBase Database Proxy
    • iconEmbedded SQL in C for OceanBase
    • iconOceanBase Call Interface
    • iconOceanBase Connector/C
    • iconOceanBase Connector/J
    • iconOceanBase Connector/ODBC
    • iconOceanBase Connector/NET
icon

OceanBase Developer Center

V4.2.2

  • Overview
    • What is ODC?
    • Features
    • Architecture
    • Limitations
    • ODC console
  • Quick Start
    • Client ODC
      • Overview
      • Install Client ODC
      • Use Client ODC
    • Web ODC
      • Overview
      • Deploy Web ODC
      • Use Web ODC
  • Data Source Management
    • Create a data source
    • Data sources and project collaboration
    • Database O&M
      • Session management
      • Global variable management
      • Recycle bin management
  • SQL Development
    • Write and execute SQL statements
    • Perform PL compilation and debugging
    • Use the command-line window
    • Edit and export the result set of an SQL statement
    • Analyze SQL statements
    • Generate test data
    • Database objects
      • Table objects
        • Overview
        • Create a table
        • Table list
        • Manage table attributes
        • Manage table data
      • View objects
        • Overview
        • Create a view
        • Manage views
      • Function objects
        • Overview
        • Create a function
        • Manage functions
      • Stored procedure objects
        • Overview
        • Create a stored procedure
        • Manage stored procedures
      • Sequence objects
        • Overview
        • Create a sequence
        • Manage sequences
      • Package objects
        • Overview
        • Create a program package
        • Manage program packages
      • Trigger objects
        • Overview
        • Create a trigger
        • Manage triggers
      • Type objects
        • Overview
        • Create a type
        • Manage types
      • Synonym objects
        • Overview
        • Create a synonym
        • Manage synonyms
  • Import and Export
    • Import schemas and data
    • Export schemas and data
  • Database Change Management
    • User Permission Management
      • Users and roles
      • Automatic authorization
    • Collaborative project management
    • Risk levels, risk identification rules, and approval processes
    • SQL check specifications
    • SQL window specification
    • Database change management
    • Lock-free schema changes
    • Synchronize shadow tables
  • Data Lifecycle Management
    • Archive data
    • Clean up data
    • Manage partitions
    • SQL plan task
  • Data Desensitization and Auditing
    • Desensitize data
    • Operation audit
  • System Integration
    • SSO integration
    • Approval integration
    • SQL approval integration
  • Deployment Guide
    • Overview
    • Preparations before deployment
    • Deploy ODC on a single node
    • Deploy ODC in high-availability mode
    • Deployment verification
  • Upgrade Guide
    • Overview
    • Preparations before upgrade
    • Upgrade single-node ODC
    • Upgrade high-availability ODC
    • Upgrade verification
    • Rollback after upgrade failed
  • Troubleshooting
    • ODC troubleshooting process
    • Collect Message
      • View the runtime environment and version information
      • View web ODC logs
      • View client ODC logs
      • View end-to-end ODC-related logs
      • View ODC MetaDB data
      • Query the index status in OceanBase Database V4.x
      • Query the index status in OceanBase Database V1.4.x to V3.2.x
      • Collect JVM runtime information
      • Use tcpdump to capture packets
    • Common Troubleshooting
      • Deployment Upgrade
        • Web ODC cannot be accessed after startup
      • Database Connection
        • Access denied in a connection trial or test
        • Connection is refused in a connection trial or test
        • Connection times out
        • `Connection reset` is reported for a time-consuming statement
        • `socket write error` or `closed by server` is reported for a connection
      • SQL Execution
        • Disconnection during SQL execution
        • `Over tenant memory limits` is reported during SQL execution
        • `Unknown thread id` is returned during SQL execution
        • `timeout` errors returned during SQL execution
        • `OutOfMemoryError` is returned during SQL execution
        • Incomplete result columns for the SELECT statement
        • Garbled Chinese characters in the SQL execution result set
        • Garbled Chinese data is returned for query of data in GBK encoding
      • PL Object
        • Debugging is not supported for invalid PL objects
        • `JSONException` is reported during PL debugging
        • Garbled variable values in debugging
        • Failed to view PL objects or garbled characters are returned
        • PL objects cannot be executed or an execution error is returned
        • ODC issues during PL debugging
        • PL anonymous block cannot be debugged
        • Alert information of a PL object is unavailable
      • Import and Export
        • Garbled Chinese characters in an imported file in GBK encoding
        • Invalid ZIP package reported during file import
        • Time-type data exported from an Oracle tenant cannot be imported
        • Mismatched columns reported during the import of a single-table CSV file
        • Failed to export a result set in ODC to an Excel file
        • Incorrect display in Excel for a result set exported in CSV format
        • Incomplete data in batch export of multiple tables
        • `javax.crypto.BadPaddingException: Given final block not properly padded` is returned for a data import or export failure
      • Client ODC Problems
        • Client ODC startup failure / H2 Database corruption: Chuck not found
        • Garbled Chinese characters in the command-line window of ODC
        • Failed to install client ODC
        • Client ODC startup failure or no response
        • `Not a valid secret key` is returned for connection creation in client ODC
        • `User does not exist` returned for connection creation in client ODC
        • High memory usage of client ODC
        • Client ODC fails to be installed or start due to a port conflict
      • Front-end Page Exception
        • JavaScript exception is thrown on the ODC page
        • No response in browser after opening ODC
        • White screen in ODC
      • Account Password Problem
        • Forgot the admin account password in ODC V3.2.0 or later
        • Forgot an account password in ODC V2.4.1 to V3.1.3
        • Forgot an account password in ODC V2.4.0 or earlier
    • FAQ
      • Installation of client ODC
      • Web ODC deployment and startup
      • FAQ
      • Command-line window
      • DDL statement display
  • Release Note
    • 90.odc-rn-4.2
      • ODC V4.2.2
      • ODC V4.2.0
      • ODC V4.2.1
    • V4.1
      • ODC V4.1.2
      • ODC V4.1.1
      • ODC V4.1.0
    • V4.0
      • ODC V4.0.2
      • ODC V4.0.0
    • V3.4
      • ODC V3.4.0
    • V3.3
      • ODC V3.3.3
      • ODC V3.3.2
      • ODC V3.3.1
      • ODC V3.3.0
    • V3.2
      • ODC V3.2.3
      • ODC V3.2.2
      • ODC V3.2.1
      • ODC V3.2.0

Download PDF

What is ODC? Features Architecture Limitations ODC console Overview Install Client ODC Use Client ODC Overview Deploy Web ODC Use Web ODC Create a data source Data sources and project collaboration Session management Global variable management Recycle bin management Write and execute SQL statements Perform PL compilation and debugging Use the command-line window Edit and export the result set of an SQL statement Analyze SQL statements Generate test data Import schemas and data Export schemas and data Users and roles Automatic authorization Collaborative project management Risk levels, risk identification rules, and approval processes SQL check specifications SQL window specification Database change management Lock-free schema changes Synchronize shadow tables Archive data Clean up data Manage partitions SQL plan task Desensitize data Operation audit SSO integration Approval integration SQL approval integration OverviewPreparations before deployment Deploy ODC on a single node Deploy ODC in high-availability modeDeployment verification OverviewPreparations before upgrade Upgrade single-node ODC Upgrade high-availability ODCUpgrade verification Rollback after upgrade failed ODC troubleshooting process View the runtime environment and version information View web ODC logsView client ODC logsView end-to-end ODC-related logsView ODC MetaDB dataQuery the index status in OceanBase Database V4.xQuery the index status in OceanBase Database V1.4.x to V3.2.xCollect JVM runtime informationUse tcpdump to capture packetsInstallation of client ODCWeb ODC deployment and startupFAQCommand-line windowDDL statement display ODC V4.2.2 ODC V4.2.0 ODC V4.2.1 ODC V4.1.2 ODC V4.1.1 ODC V4.1.0 ODC V4.0.2 ODC V4.0.0ODC V3.4.0ODC V3.3.3 ODC V3.3.2 ODC V3.3.1 ODC V3.3.0 ODC V3.2.3 ODC V3.2.2 ODC V3.2.1 ODC V3.2.0
OceanBase logo

The Unified Distributed Database for the AI Era.

Follow Us
Products
OceanBase CloudOceanBase EnterpriseOceanBase Community EditionOceanBase seekdb
Resources
DocsBlogLive DemosTraining & Certification
Company
About OceanBaseTrust CenterLegalPartnerContact Us
Follow Us

© OceanBase 2026. All rights reserved

Cloud Service AgreementPrivacy PolicySecurity
Contact Us
Document Feedback
  1. Documentation Center
  2. OceanBase Developer Center
  3. V4.2.2
iconOceanBase Developer Center
V 4.2.2
  • V 4.4.2
  • V 4.4.1
  • V 4.4.0
  • V 4.3.4
  • V 4.3.3
  • V 4.3.2
  • V 4.3.1
  • V 4.3.0
  • V 4.2.4
  • V 4.2.3
  • V 4.2.2
  • V 4.2.1
  • V 4.2.0
  • V 4.1.3 and earlier

Upgrade high-availability ODC

Last Updated:2026-04-13 07:40:37  Updated
share
What is on this page
Stop ODC of the earlier version
Back up the MetaDB
Load and run an ODC image
Load the image
Run the image
Upgrade Nginx image
Stop and delete the old image
Load the new image
Configure the configuration file
Start the image

folded

share

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.

  1. Run the docker ps -a command 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 ID column based on the image name in the IMAGE column. 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   obodc
    
  2. After 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
    8bfecbc1cd03
    
  3. Run 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.
  1. To obtain the ODC image on the host, select the required image from the Maintenance Tools of the OceanBase Download Center.

  2. 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
  • Maps the /var/log/odc directory of the host to the /opt/odc/log directory in the ODC container. If the /var/log/odc directory does not exist on the host, run the mkdir -p /var/log/odc command to create one.
  • Maps the /var/data/odc directory of the host to the /opt/odc/data directory in the ODC container. If the /var/data/odc directory does not exist on the host, run the mkdir -p /var/data/odc command to create one.
--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
  • The ---cpu-period parameter specifies the interval at which the CPU cores of the Docker container are reallocated. Unit: μs.
  • The ---cpu-quota parameter specifies the maximum time for running the current Docker container in this interval. Unit: μs.
  • You can use these two parameters in combination to specify the number of CPU cores that the Docker container uses. The value is calculated by dividing 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.

    Notice

    The initial password must meet the following requirements:

    • Contains at least two digits.
    • Contains at least two uppercase letters.
    • Contains at least two lowercase letters.
    • Contains at least two special characters, which can be . _ + @ # $ %
    • Contains 8 to 32 characters without spaces or other special characters.

    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.

    1. Run the docker ps -a command 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 ID column based on the image name in the IMAGE column. 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   nginx
      
    2. After 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
      8bfecbc1cd03
      
    3. Run 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_timeout parameter to a value not longer than 75 seconds. For more information, see proxy_connect_timeout.
    • If you do not set the proxy_next_upstream parameter to off, 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.

    Previous topic

    Upgrade single-node ODC
    Last

    Next topic

    Upgrade verification
    Next
    What is on this page
    Stop ODC of the earlier version
    Back up the MetaDB
    Load and run an ODC image
    Load the image
    Run the image
    Upgrade Nginx image
    Stop and delete the old image
    Load the new image
    Configure the configuration file
    Start the image