PTK-based Installation

This document introduces how to install Uqbar using PTK.

PTK (Provisioning Toolkit) is a software installation, and operation and maintenance tool developed for MogDB to facilitate the installation and deployment of the MogDB database, and also used for Uqbar.

You can run the following command to check operating systems where Uqbar can be installed using PTK.

[root@hostname]# ptk candidate os
    ID    |                      OS                      | Installation package |    Deploy tested     | Fully compatibility tested
          |                                              |                      |     (OS Version)     |      (MogDB Version)
----------+----------------------------------------------+----------------------+----------------------+-----------------------------
  1007010 | CentOS Linux 7 (Core) (x86_64)               | CentOS               | 7.6.1810             | all versions
  1008010 | CentOS 8 (x86_64)                            | openEuler            | 8.0.1905             |
  1008020 | CentOS 8 (arm64)                             | openEuler            | 8.0.1905             |
  1120010 | openEuler 20 (x86_64)                        | openEuler            | 20.03                | < 5.0.0 || > 5.0.1
  1120020 | openEuler 20 (arm64)                         | openEuler            | 20.03                | < 5.0.0 || > 5.0.1
  1122010 | openEuler 22 (x86_64)                        | openEuler            | 22.03                |
  1122020 | openEuler 22 (arm64)                         | openEuler            | 22.03                |
  1210010 | Kylin V10 (x86_64)                           | kylin                | V10 (Tercel)         | all versions
  1210020 | Kylin V10 (arm64)                            | kylin                | V10 (Tercel)         | all versions
  1320010 | UOS 20 A (x86_64)                            | openEuler            | 1050a                |
  1320020 | UOS 20 A (arm64)                             | openEuler            | 1050a                |
  1420010 | UOS 20 D/E (x86_64)                          | openEuler            | 1040d/1050d/1050e    |
  1420020 | UOS 20 D/E (arm64)                           | openEuler            | 1040d/1050d          |
  1518010 | Ubuntu 18.04.6 LTS (Bionic Beaver) (x86_64)  | CentOS               | 18.04.6              |
  1518020 | Ubuntu 18.04.6 LTS (Bionic Beaver) (arm64)   | openEuler            | 18.04.6              |
  1520010 | Ubuntu 20 LTS (Focal Fossa) (x86_64)         | CentOS               | 20.04.3              |
  1520020 | Ubuntu 20 LTS (Focal Fossa) (arm64)          | openEuler            | 20.04.5              |
  1522010 | Ubuntu 22 LTS (Jammy Jellyfish) (x86_64)     | CentOS               | 22.04                |
  1522020 | Ubuntu 22 LTS (Jammy Jellyfish) (arm64)      | openEuler            | 22.04.1              |
  1607010 | Red Hat Enterprise Linux 7 (x86_64)          | CentOS               | 7.5 (Maipo)          |
  1608010 | Red Hat Enterprise Linux 8 (Ootpa) (x86_64)  | openEuler            | 8.5                  |
  1608020 | Red Hat Enterprise Linux 8.2 (Ootpa) (arm64) | openEuler            | 8.2                  |
  1609010 | Red Hat Enterprise Linux 9.0 (Plow) (x86_64) | openEuler            | 9.0                  |
  1609020 | Red Hat Enterprise Linux 9.0 (Plow) (arm64)  | openEuler            | 9.0                  |
  1702010 | EulerOS 2 (x86_64)                           | CentOS               | 2.0-SP3              |
  1702020 | EulerOS 2 (arm64)                            | openEuler            | 2.0-SP3              |
  1812010 | SLES 12SP5 (x86_64)                          | CentOS               | 12SP5                |
  1815010 | SUSE Linux Enterprise Server 15 SP4 (x86_64) | CentOS               | 15SP4                |
  1907010 | Oracle Linux 7 (x86_64)                      | CentOS               | 7.9 (Maipo)          |
  1908010 | Oracle Linux 8 (x86_64)                      | openEuler            | 8.6 (Ootpa)          |
  2008010 | Rocky Linux 8 (Green Obsidian) (x86_64)      | openEuler            | 8.5                  |
  2107010 | NeoKylin V7 (x86_64)                         | CentOS               | V7Update6            |
  2222010 | FusionOS 22 (x86_64)                         | openEuler            | 22.0.2               |
  2222020 | FusionOS 22 (arm64)                          | openEuler            | 22.0.2               |
  2310010 | Debian GNU/Linux 10 (buster) (x86_64)        | CentOS               | 10 (buster)          |
  2310020 | Debian GNU/Linux 10 (buster) (arm64)         | openEuler            | 10 (buster)          |
  2311010 | Debian GNU/Linux 11 (bullseye) (x86_64)      | CentOS               | 11 (bullseye)        |
  2311020 | Debian GNU/Linux 11 (bullseye) (arm64)       | openEuler            | 11 (bullseye)        |
  2407010 | Anolis OS Linux 7 (x86_64)                   | CentOS               | 7.9 GA (kernel:RHCK) |
  2408010 | Anolis OS 8 (x86_64)                         | openEuler            | 8.6 GA (kernel:RHCK) |
  2408020 | Anolis OS 8 (arm64)                          | openEuler            | 8.6 GA (kernel:ANCK) |

Note:

The PTK tool itself can run on a variety of operating systems, including Linux, macOS, and Windows. However, since Uqbar currently only runs on Linux, you need to ensure that the server on which you want to run the Uqbar database is a Linux operating system.

PTK v0.5 or newer is required for Uqbar installation. Otherwise, the installation may fail.

Installation Preparation

For details about environment requirements and operating system configuration, see Environment Requirement and Operating System Configuration.

PTK Installation

The following introduces how to perform quick online installation. PTK supports online and offline installation. For details about offline installation, see PTK Installation.

Run the following command to install PTK.

curl --proto '=https' --tlsv1.2 -sSf https://cdn-mogdb.enmotech.com/ptk/install.sh | sh

Information similar to the following is displayed (the information varies depending on the type of Shell for running PTK).

info: downloading ptk package
Detected shell: bash
Shell profile:  /root/.bashrc
ptk has been added to PATH in /root/.bashrc
open a new terminal or source /root/.bashrc to active it
Installed path: /root/.ptk/bin/ptk

Run the source command or open a terminal to make PTK environment variables take effect. For example, use bash as an example.
```
source $HOME/.bashrc
```

Installing Uqbar Using PTK

Prepare a Topology Configuration File

PTK installation requires the user to provide the configuration file config.yaml. PTK supports single-node installation and multi-node installation. The following uses the installation of only one node and one primary and standby node as an example.

Single-node installation

# config.yaml
global:
    cluster_name: uqbar1
    user: omm
    group: omm
    base_dir: /opt/uqbar
db_servers:
    - host: 127.0.0.1
      db_port: 26000

If default settings are used in the configuration file, PTK will perform the following operations:

Uqbar is installed on the local server.
The operating system user for running the database is omm, the user group name is omm, and the user does not have a default password.
The database is installed in the /opt/uqbar directory where four directories app, data, log, and tool will be created for storing database software, data files, database logs, and database-related tools.
The listening port of the database is 26000.

Primary/standby node installation

# config.yaml
global:
    cluster_name: uqbar_cluster1
    user: omm
    group: omm
    base_dir: /opt/uqbar
db_servers:
    - host: 192.168.0.1
      db_port: 26000
      role: primary
      ssh_option:
        port: 22
        user: root
        password: [Enter the SSH login password, which should be encrypted by `ptk encrypt`.]
    - host: 192.168.0.2
      db_port: 26000
      role: standby
      ssh_option:
        port: 22
        user: root
        password: [Enter the SSH login password, which should be encrypted by `ptk encrypt`.]

Perform System Check on the Local Server

ptk checkos -f config.yaml

Make sure the check result includes OK or Warning. If Abnormal occurs, the users needs to modify system parameters based on logs.

If there is an Abnormal check result, PTK will automatically generate a root_fix_***.sh file, which can be used to quickly correct system parameters; if there is an ExecuteError check result, it represents a PTK execution failure, requiring the user to adjust the system environment based on the error message.

Install Uqbar

PTK supports customization of the installation package and manual downloading of the installation package. For example, run the following command to install Uqbar using the installation package in the current directory. During the installation, you will be prompted to enter the initial password of the database user, and make sure that you take a note of the password. After automatic installation of Uqbar using PTK, the database instance will be started.

ptk install -f config.yaml --pkg ./Uqbar-2.0.0-Kylin-x86_64-all.tar.gz

After successful installation, you can check the instance information by running the ptk lscommand.

[root@hostname]# ptk ls
  cluster_name |  id  |        addr        |   user   |        data_dir        |            db_version            |     create_time     | comment
---------------+------+--------------------+----------+------------------------+----------------------------------+---------------------+----------
  uqbar1     | 6001 | xxx.xx.x.xxx:26000 | omm | /opt/uqbar/data     | Uqbar 2.0.0 (build xxxxxxxx)     | 2023-11-30T16:29:46 |

Access Uqbar

su - omm
gsql -r

Uninstalling Uqbar Using PTK

During uninstallation, PTK will check whether the cluster is in the running status. A cluster in the running status cannot be uninstalled. You need to stop the cluster and then uninstall the cluster.

Note: Once a database is uninstalled, it cannot be recovered. Please execute operation with caution.

You can run the ptk uninstall -n CLUSTER_NAME command on the server where PTK is installed to uninstall a cluster.

To uninstall a cluster, you need to specify the cluster name, you can run the ptk ls command to query the cluster name.

During uninstallation, PTK will ask you whether to delete the cluster topology information, system user, and database data.

Please perform operations with cautions, avoiding data loss due to incorrect operations.

If you are sure to delete the data directory, PTK delete only the data directory and will not delete its parent directory. You need to manually delete the parent directory.

For details about PTK usage, see About PTK.