docs(Quick Deployment and Compiling Methods): update docs

Make the document more user-friendly for new users stoneatom#372
Nliver · Aug 5, 2022 · dc86537 · dc86537
1 parent 5e23c20
commit dc86537
Show file tree

Hide file tree

Showing 14 changed files with 832 additions and 535 deletions.
diff --git a/Docs/02-getting-started/quick-deployment.md b/Docs/02-getting-started/quick-deployment.md
@@ -5,40 +5,43 @@ sidebar_position: 3.1
 
 # Quick Deployment
 
-## 1. Download the latest package
+## **1. Download the latest package**
 Click [here](https://static.stoneatom.com/stonedb-ce-5.6-v1.0.0.el7.x86_64.tar.gz) to download the latest installation package of StoneDB.
-## 2. Upload and decompress the TAR package
+## **2. Upload and decompress the TAR package**
 ```shell
 tar -zxvf stonedb-ce-5.6-v1.0.0.el7.x86_64.tar.gz
 ```
 Upload the installation package to the directory. The name of the folder extracted from the package is **stonedb56**.
-## 3. Check dependencies
+## **3. Check dependencies**
 ```bash
 cd /stonedb56/install/bin
 ldd mysqld
 ldd mysql
 ```
-If the command output contains keywords **not found**, some dependencies are missing and must be installed.
-## 4. Modify the configuration file
+If the command output contains keywords **not found**, some dependencies are missing and must be installed. <br />For example, `libsnappy.so.1 => not found` is returned:
+
+- If your OS is Ubuntu, run the `sudo apt search libsnappy` command. The command output will inform you to install `libsnappy-dev`. 
+- If your OS is RHEL or CentOS, run the `yum search all snappy` command. The command output will inform you to install **snappy-devel** and **snappy**.
+## **4. Modify the configuration file**
 ```bash
 cd /stonedb56/install/
 cp stonedb.cnf stonedb.cnf.bak
 vi stonedb.cnf
 ```
 Modify the path and parameters. If the installation folder is **stonedb**, you only need to modify the parameters.
-## 5. Create an account
+## **5. Create an account**
 ```bash
 groupadd mysql
 useradd -g mysql mysql
 passwd mysql
 ```
-## 6. Execute reinstall.sh
+## **6. Execute reinstall.sh**
 ```bash
 cd /stonedb56/install
 ./reinstall.sh
 ```
 The process of executing the script is to initialize and start the StoneDB.
-## 7. Log in to StoneDB
+## **7. Log in to StoneDB**
 ```shell
 /stonedb56/install/bin/mysql -uroot -p -S /stonedb56/install/tmp/mysql.sock 
 Enter password: 
@@ -65,7 +68,7 @@ mysql> show databases;
 +--------------------+
 7 rows in set (0.00 sec)
 ```
-## 8. Stop StoneDB
+## **8. Stop StoneDB**
 ```shell
 /stonedb56/install/bin/mysqladmin -uroot -p -S /stonedb56/install/tmp/mysql.sock shutdown
-```
+```
diff --git a/Docs/04-developer-guide/00-compiling-methods/compile-using-centos7.md b/Docs/04-developer-guide/00-compiling-methods/compile-using-centos7.md
@@ -6,10 +6,16 @@ sidebar_position: 5.12
 # Compile StoneDB on CentOS 7
 
 This topic describes how to compile StoneDB on CentOS 7.
-## Prerequisites
-The source code of StoneDB has been downloaded.
+## Precautions
+Ensure that the tools and third-party libraries used in your environment meet the following version requirements:
+
+- GCC 9.3.0
+- Make 3.82 or later
+- CMake 3.7.2 or later
+- marisa 0.77
+- RocksDB 6.12.6
+- Boost 1.66
 
-Download link:  [https://github.com/stoneatom/stonedb.git](https://github.com/stoneatom/stonedb.git)
 ## Procedure
 ### Step 1. Install the dependencies
 ```shell
@@ -51,36 +57,39 @@ yum install -y libaio-devel
 yum install -y libicu
 yum install -y libicu-devel
 ```
-### Step 2. Install GCC 7.3.0
-Before executing **stonedb_build.sh** to compile StoneDB, you must ensure the GCC version is 7.3.0.
+### Step 2. Install GCC 9.3.0
+Before performing the follow-up steps, you must ensure the GCC version is 9.3.0.
 
 You can run the following command to check the GCC version.
 ```shell
 gcc --version
 ```
-If the version is earlier than 7.3.0, perform the following steps to upgrade GCC.
+If the version is earlier than 9.3.0, perform the following steps to upgrade GCC.
 
 1. Install the SCL utility.
 ```shell
 yum install centos-release-scl scl-utils-build -y
 ```
 
-2. Install GCC, GCC-C++, or GDB of version 7.3.0.
+2. Install GCC, GCC-C++, or GDB of version 9.3.0.
 ```shell
-yum install devtoolset-7-gcc.x86_64 devtoolset-7-gcc-c++.x86_64 devtoolset-7-gcc-gdb-plugin.x86_64 -y
+yum install devtoolset-9-gcc.x86_64 devtoolset-9-gcc-c++.x86_64 devtoolset-9-gcc-gdb-plugin.x86_64 -y
 ```
 
-3. Switch the version to 7.3.0.
+3. Switch the version to 9.3.0.
 ```shell
-scl enable devtoolset-7 bash
+scl enable devtoolset-9 bash
 ```
 
-4. Check that the version is switched to 7.3.0.
+4. Check that the version is switched to 9.3.0.
 ```shell
 gcc --version
 ```
-### Step 3. Install CMake, Make, and third-party libraries
-Before compiling StoneDB, install CMake 3.7or later, Make 3.82 or later, and the following third-party libraries: marisa, RocksDB, and Boost.
+### Step 3. Install third-party libraries
+Ensure that the CMake version in your environment is 3.7.2 or later and the Make version is 3.82 or later. Otherwise, install CMake, Make, or both of them of the correct versions.
+:::info
+StoneDB is dependent on marisa, RocksDB, and Boost. You can specify an installation directory for marisa, RocksDB, or Boost, when compiling it, or the library will be saved in **/usr/local **by default. In the following example, each directory is specified with an installation directory. There is also no need to specify the installation directory for StoneDB.
+:::
 
 1. Install CMake.
 ```shell
@@ -111,17 +120,34 @@ autoreconf -i
 ./configure --enable-native-code --prefix=/usr/local/stonedb-marisa
 make && make install 
 ```
+The installation directory of marisa in the example is **/usr/local/stonedb-marisa**. You can change it based on your actual conditions.
 
 4. Install RocksDB.
 ```shell
-wget https://github.com/facebook/rocksdb/archive/refs/tags/v4.13.tar.gz
-tar -zxvf v4.13.tar.gz
-cd rocksdb-4.13
-make shared_lib
-make install-shared INSTALL_PATH=/usr/local/stonedb-gcc-rocksdb
-make static_lib
-make install-static INSTALL_PATH=/usr/local/stonedb-gcc-rocksdb
+wget https://github.com/facebook/rocksdb/archive/refs/tags/v6.12.6.tar.gz
+tar -zxvf v6.12.6.tar.gz
+cd rocksdb-6.12.6
+
+cmake ./ \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DCMAKE_INSTALL_PREFIX=/usr/local/stonedb-gcc-rocksdb \
+  -DCMAKE_INSTALL_LIBDIR=/usr/local/stonedb-gcc-rocksdb \
+  -DWITH_JEMALLOC=ON \
+  -DWITH_SNAPPY=ON \
+  -DWITH_LZ4=ON \
+  -DWITH_ZLIB=ON \
+  -DWITH_ZSTD=ON \
+  -DUSE_RTTI=ON \
+  -DROCKSDB_BUILD_SHARED=ON \
+  -DWITH_GFLAGS=OFF \
+  -DWITH_TOOLS=OFF \
+  -DWITH_BENCHMARK_TOOLS=OFF \
+  -DWITH_CORE_TOOLS=OFF 
+
+make -j`nproc`
+make install -j`nproc`
 ```
+The installation directory of RocksDB in the example is **/usr/local/stonedb-gcc-rocksdb**. You can change it based on your actual conditions.
 
 5. Install Boost.
 ```shell
@@ -131,13 +157,41 @@ cd boost_1_66_0
 ./bootstrap.sh --prefix=/usr/local/stonedb-boost
 ./b2 install --with=all
 ```
+The installation directory of Boost in the example is **/usr/local/stonedb-boost**. You can change it based on your actual conditions.
+:::info
+During the compilation, the occurrences of keywords **warning** and** failed** are normal, unless **error** is displayed and the CLI is automatically closed.
+:::
 ### Step 4. Compile StoneDB
-Execute the following script to compile StoneDB:
+Currently, StoneDB has two branches: StoneDB-5.6 (for MySQL 5.6) and StoneDB-5.7 (for MySQL 5.7). The link provided in this topic is to the source code package of StoneDB-5.7. In the following example,the source code package is saved to the root directory and is switched to StoneDB-5.6 for compilation. 
+:::info
+GCC 9.3.0 or later supports the compilation of StoneDB-5.6 and allows you to specify the installation directories for RocksDB and marisa. We are working on the support for GCC 7.3.0 and for compilation of StoneDB-5.7.
+:::
 ```shell
+cd /
+git clone https://github.com/stoneatom/stonedb.git
+cd stonedb
+git checkout remotes/origin/stonedb-5.6
+```
+Before compilation, modify the compilation script as follows:
+
+1. Change the installation directory of StoneDB based on your actual conditions. In the example, **/stonedb56/install** is used.
+1. Change the installation directories of marisa, RocksDB, and Boost based on your actual conditions.
+```shell
+### Modify the compilation script.
 cd /stonedb/scripts
-./stonedb_build.sh
+vim stonedb_build.sh
+...
+install_target=/stonedb56/install
+...
+-DDOWNLOAD_BOOST=0 \
+-DWITH_BOOST=/usr/local/stonedb-boost/ \
+-DWITH_MARISA=/usr/local/stonedb-marisa \
+-DWITH_ROCKSDB=/usr/local/stonedb-gcc-rocksdb \
+2>&1 | tee -a ${build_log}
+
+### Execute the compilation script.
+sh stonedb_build.sh
 ```
-After the compilation is complete, a folder named **/stonedb57** is generated.
 ### Step 5. Start StoneDB
 Perform the following steps to start StoneDB.
 
@@ -148,47 +202,71 @@ useradd -g mysql mysql
 passwd mysql
 ```
 
-2. Execute **reinstall.sh**.
+2. Manually install StoneDB.
+
+If the installation directory after compilation is not **/stonedb56**, files **reinstall.sh**, **install.sh**, and **my.cnf** will not automatically generated. You need to manually create directories, and then initialize and start StoneDB. You also need to configure parameters in file **my.cnf**, including the installation directories and port.
 ```shell
-cd /stonedb57/install
-./reinstall.sh
+### Create directories.
+mkdir -p /data/stonedb56/install/data/innodb
+mkdir -p /data/stonedb56/install/binlog
+mkdir -p /data/stonedb56/install/log
+mkdir -p /data/stonedb56/install/tmp
+chown -R mysql:mysql /data
+
+### Configure parameters in my.cnf.
+vim /data/stonedb56/install/my.cnf
+[mysqld]
+port      = 3306
+socket    = /data/stonedb56/install/tmp/mysql.sock
+datadir   = /data/stonedb56/install/data
+pid-file  = /data/stonedb56/install/data/mysqld.pid
+log-error = /data/stonedb56/install/log/mysqld.log
+
+chown -R mysql:mysql /data/stonedb56/install/my.cnf
+
+### Initialize StoneDB.
+/data/stonedb56/install/scripts/mysql_install_db --datadir=/data/stonedb56/install/data --basedir=/data/stonedb56/install --user=mysql
+
+### Start StoneDB.
+/data/stonedb56/install/bin/mysqld_safe --defaults-file=/data/stonedb56/install/my.cnf --user=mysql &
 ```
-:::info
-The aim of executing the script is to initialize and start StoneDB.
-:::
 
-3. Log in to StoneDB.
+3. Execute reinstall.sh to automatically install StoneDB.
 
- Before you log in to StoneDB, you must find the password of the super admin in **/stonedb57/install/log/mysqld.log**.
+If the installation directory after compilation is **/stonedb56**, execute **reinstall.sh**. Then, StoneDB will be automatically installed.
 ```shell
-more /stonedb57/install/log/mysqld.log |grep password
-2022-07-12T11:41:59.849676Z 1 [Note] A temporary password is generated for root@localhost: %xjqgHux(6pr
+cd /stonedb56/install
+./reinstall.sh
 ```
+:::info
+Differences between **reinstall.sh** and **install.sh**:
+
+- **reinstall.sh** is the script for automatic installation. When the script is being executed, directories are created, and StoneDB is initialized and started. Therefore, do not execute the script unless for the initial startup of StoneDB. Otherwise, all directories will be deleted and StoneDB will be initialized again.
+- **install.sh** is the script for manual installation. You can specify the installation directories based on your needs and then execute the script. Same as **reinstall.sh**, when the script is being executed, directories are created, and StoneDB is initialized and started. Therefore, do not execute the script unless for the initial startup. Otherwise, all directories will be deleted and StoneDB will be initialized again.
+:::
+
+4. Log in to StoneDB.
 ```shell
-/stonedb57/install/bin/mysql -uroot -p -S /stonedb57/install//tmp/mysql.sock
+/stonedb56/install/bin/mysql -uroot -p -S /stonedb56/install/tmp/mysql.sock
 Enter password: 
 Welcome to the MySQL monitor.  Commands end with ; or \g.
-Your MySQL connection id is 3
-Server version: 5.7.36-StoneDB-debug-log
+Your MySQL connection id is 2
+Server version: 5.6.24-StoneDB-debug build-
 
 Copyright (c) 2000, 2022 StoneAtom Group Holding Limited
 Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
 
-root@localhost [(none)]> show databases;
-ERROR 1820 (HY000): You must reset your password using ALTER USER statement before executing this statement.
-root@localhost [(none)]> alter user 'root'@'localhost' identified by 'xxx';
-Query OK, 0 rows affected (0.00 sec)
-
-root@localhost [(none)]> show databases;
+mysql> show databases;
 +--------------------+
 | Database           |
 +--------------------+
 | information_schema |
 | cache              |
+| innodb             |
 | mysql              |
 | performance_schema |
-| sys                |
 | sys_stonedb        |
+| test               |
 +--------------------+
-6 rows in set (0.00 sec)
+7 rows in set (0.00 sec)
 ```