Deploying a Cluster on Ubuntu 20.04

Operating System and Platform Requirements

Operating System	Supported CPU Architectures
Ubuntu 20.04 LTS	x86_64 aarch64

Example Cluster Information

This document uses a three-node cluster as an example: the master node is mdw, and the two segment nodes are sdw1 and sdw2.

Server Installation

The server installation process consists of five steps: checking basic server information, installation preparation, installing the database DEB package, deploying the database, and post-installation configuration.

1 Check Basic Server Information

Before starting the installation, check the basic system information. This is a good practice, as understanding the server helps you plan the cluster deployment more effectively.

Step	Command	Purpose
1	`free -h`	View memory usage
2	`df -h`	View disk space
3	`lscpu`	View number of CPUs
4	`lsb_release -a`	View OS version
5	`uname -a`	Output all kernel information in the following order (if -p or -i cannot be determined, they are omitted): kernel name; hostname; kernel release; kernel version; hardware architecture; processor type (non-portable); hardware platform (non-portable); operating system name
6	`tail -11 /proc/cpuinfo`	View CPU details

2 Installation Preparation

Note!
Commands in sections 2 (Installation Preparation) and 3 (Database DEB Package Installation) must be executed on all nodes.

2.1 Update Software List

This document assumes you have already configured the software sources in the /etc/apt/sources.list file. Next, update the package list as root or with root privileges.

# apt update

APT (Advanced Package Tool) manages software packages, including downloading, installing, resolving dependencies, and updating the package index.

2.2 Set Locale

Set the locale as root or with sudo privileges.

# apt install -y locales && sudo locale-gen "en_US.UTF-8" && sudo update-locale LC_ALL="en_US.UTF-8"

2.3 Modify Host Configuration

Ensure each node has a persistent hostname. If not set, use the following command to configure it. For example, on the master node:

# hostnamectl set-hostname mdw

Similarly, set hostnames for the two segment nodes:

# hostnamectl set-hostname sdw1

# hostnamectl set-hostname sdw2

Ensure all nodes can communicate with each other using hostnames or IP addresses. First, install the vim tool.

# apt install vim

Add entries to /etc/hosts to map hostnames to local network interface addresses. For example, the /etc/hosts file on each of the three nodes should contain lines similar to:

# vim /etc/hosts
192.168.100.10 mdw
192.168.100.11 sdw1
192.168.100.12 sdw2

After editing, press Esc, then enter :wq to save and exit.

2.4 Copy DEB Package from Local Machine to Servers

Note!
Obtain the DEB package download link from the official email.

Copy the DEB package to be installed from your local machine to all nodes.

~ scp <local file path> <username>@<server IP>:<server file path>

3 Install YMatrix DEB Package

Note!
On all server nodes, install the database DEB package as root or with sudo privileges using the apt command below. System dependencies will be automatically installed.

# apt install -y /path/to/matrixdb6_6.2.0+enterprise-1_amd64.deb

Note!
In actual installation, replace the filename with the latest downloaded DEB package name, and /path/to/ with the correct path. Use ./ if the file is in the current directory.

After successful installation, supervisord and MXUI processes start automatically. These background services provide the web-based UI and process management.

If you need to configure ports, modify the /etc/matrixdb6/defaults.conf file after installing the DEB package. This step is required only on the Master node.

# vim /etc/matrixdb6/defaults.conf

4 Install Python Dependencies and Set Default Python Version

On all nodes, use root or sudo privileges to run the following commands to install Python packages required by YMatrix. Note that source greenplum_path.sh must be executed to ensure correct dependency versions are installed.

# apt install -y \
   gcc \
   python3-dev \
   python3-pip \
   python3-psutil \
   python3-pygresql \
   python3-testresources
# update-alternatives --install /usr/bin/python python /usr/bin/python3 50

5 Database Deployment

YMatrix provides a graphical deployment wizard. Remote access to the GUI is available via ports 8240 and 4617. After installation, these ports are open by default on all nodes. The MXUI process provides the web interface.

Note!
If the graphical interface is unavailable, refer to command-line deployment.

Access the installation wizard using a browser at the following URL. The server whose IP address you enter will become the Master node of your cluster (in this example, mdw):

http://<IP>:8240/

On the first page of the wizard, enter the superuser password. You can view it using the sudo more /etc/matrixdb6/auth.conf command.

On the second page, select "Multi-node Deployment", then click Next.

Proceed with the four steps of multi-node deployment.

Step 1: Add Nodes
Click the "Add" button.

Enter the IP addresses, hostnames, or FQDNs of sdw1 and sdw2 in the text box, click "Confirm", then click "Next".

Step 2: Configure Cluster Parameters
"Data Mirroring" determines whether segment nodes include backup mirrors. Enable this option in production environments to achieve high availability. The system automatically suggests the largest disk and an appropriate number of segments based on system resources. Adjust according to your use case. The configured cluster topology can be viewed in the diagram. Click "Next" after confirmation.

Step 3: Set Data Storage and etcd Paths
Select a storage path for etcd on each server. The etcd cluster will be created on an odd number of randomly selected servers to ensure election consistency and avoid ties.

If you check the top-right checkbox to deploy etcd on data disks, be aware of the associated risks.

Step 4: Execute Deployment
This step displays the previously configured parameters. Confirm the settings, then click "Deploy".

The system automatically deploys the cluster and shows detailed steps and progress. When all steps complete successfully, deployment is finished.

Deployment completed.

6 Post-Installation Configuration

6.1 Configure sysstat

On all nodes, edit the sysstat file and change ENABLED="false" to ENABLED="true". Press esc, then enter :wq to save and exit.

# sudo vi /etc/default/sysstat

Restart the service.

# sudo service sysstat restart

6.2 Enable Remote Database Access

By default, YMatrix allows remote connections. If "Allow remote access to database" was not selected during installation, manually add a line like the following to the $MASTER_DATA_DIRECTORY/pg_hba.conf file to allow any user from any IP to connect with password authentication:

# host  all       all   0.0.0.0/0  md5

You can restrict the IP range or database names based on security requirements.

After making changes, switch to the mxadmin user and reload the pg_hba.conf configuration file:

# su - mxadmin
$ mxstop -u

5.3 Using Database Management Tools

Use the following commands to start, stop, restart, or check the status of the YMatrix cluster:

Command	Purpose
`mxstop -a`	Stop the cluster. (Stops only after all sessions end; may hang if active sessions exist.)
`mxstop -af`	Forcefully stop the cluster immediately.
`mxstop -arf`	Restart the cluster. Waits for currently executing SQL statements to finish. (May hang if active sessions exist.)
`mxstate -s`	Check cluster status