Install OpenResty Edge

# 1. Architecture

OpenResty Edge contains three main roles (OpenResty Edge Admin, OpenResty Edge Log Server, OpenResty Edge Node), and the relationship between the three components is as follows:

• OpenResty Edge Admin: Edge Admin for short, used to control and manage the OpenResty Edge Node.
• OpenResty Edge Log Server: short for Log Server, Used for metrics, log storage and viewing.
• OpenResty Edge Node: Edge Node for short, is the gateway server that carries user traffic.

In addition, there are two data storage roles.

• OpenResty Edge Admin Database: Edge Admin Database for short, is the database used by Edge Admin to persist the Edge Node’s configuration.
• OpenResty Edge Log Server Database: Log Server Database for short, is the database used by Log Server to persist Edge Node’s metrics and log data.

# 2. Deployment recommendation

A formal environment installation of OpenResty Edge requires at least three machines, with Edge Admin, Log Server, and Edge Node components installed.

If you are deploying a test environment, Edge Admin and Log Server can also be installed on the same machine.

For gateway clusters with a scale of about 10 nodes, we recommend the following:

• Edge Admin: A machine with at least a 4-core processor, 16G RAM and a 200G SSD hard drive.

• Log Server: A machine with at least a 4-core processor, 16G RAM and a 200G SSD hard drive.

• Edge Node: relatively flexible, depending on business volume, roughly 1 core with 2G memory; the larger, the better. For example, 8 cores, 16 GB of memory, and a 200G hard drive.

For the environment with more than 10 nodes, you need to upgrade the configuration according to the actual scenario, and for larger clusters, you can also deploy Edge Admin Database and Log Server Database to separate machines, as shown in the following figure.

To make sure data security, we recommend to follow the section Database Backup and High Availability for configuration.

# 3. Installation

• openresty-edge-VERSION.tar.gz

This file will be available in the Download Center. You need to register an account in the openresty.com, login to the Download Center and download this file.

Here VERSION is the version of the configuration package, in the later installation steps, VERSION should be replaced with the actual version, such as openresty-edge-0.0.1-4.or.tar.gz, for this version, please refer to the latest file in the Download Center.

# 3.1 Set the firewall whitelist

Edge Admin, Edge Node, Log Server machines will access the following public addresses for downloading software packages and synchronization of license information. If your network has a firewall, you need to enable whitelisting to allow access to these addresses.

openresty.com 443
openresty.org 443
pkg.openresty.com 443
api.openresty.com 443

# 3.2 OpenResty Edge Admin Database Installation

If Edge Admin and Edge Admin Database are deployed on two separate machines, the machine where Edge Admin Database is located also needs to expose port 5432 to Edge Admin.

# 3.2.1 Installation

• Copy openresty-edge-VERSION.tar.gz to the current directory.

• Decompress this file.

  tar -xvf openresty-edge-VERSION.tar.gz
  

• Run the installer.

  cd openresty-edge-VERSION
  sudo /bin/bash openresty-edge-installer.sh
  

• Enter the action you want to perform Install.

  [1] Install
  [2] Upgrade
  [3] Downgrade
  [4] Uninstall
  What would you like to do? 1
  What you choose is: Install.
  

• Enter the version you want to install (You can obtain the latest version information from Changelog).

  Which version (like 22.12.1) would you like to install?  22.12.1
  

• Enter the component you want to install Edge Admin Database.

  [1] Edge Admin Database
  [2] Log Server Database
  [3] Edge Admin
  [4] Log Server
  [5] Edge Node
  Which component would you like to install? 1
  What you choose is: Edge Admin Database.
  

• If successful, the following prompt will be displayed at the end.

  Great! Init admin database successfully.
  

# 3.2.2 Verify the Installation

• You can also check if the process is started by using the following command.

  ps aux | grep postgres
  

• You can also check if there is any abnormal information in the Edge Admin Database log. The log directory is /var/postgres12/data/pg_log, you can get the latest log content by the following command.

  sudo ls -rt /var/postgres12/data/pg_log/* | tail -n1 | xargs sudo tail -n 50
  

# 3.3 OpenResty Edge Admin Installation

The Edge Admin machine needs to expose two ports 443 and 12345, port 443 for accessing the Edge Admin backend and port 12345 for communicating with Edge Node components.

# 3.2.1 Installation

• The procedure is similar to the previous one, with the component Edge Admin selected during installation.

  [1] Edge Admin Database
  [2] Log Server Database
  [3] Edge Admin
  [4] Log Server
  [5] Edge Node
  Which component would you like to install? 3
  What you choose is: Edge Admin.
  

• Put the SSL certificate and private key here.

  This certificate is used to access Edge Admin, after configuring this certificate you can use domain name to access Edge Admin. The certificate can be obtained from SSL certificate providers such as Let’s Encrypt, ZeroSSL, etc. You can also use openssl tool to generate a self-signed certificate. If you don’t have a certificate yet, you can skip it, and you will be using the self-signed certificate that comes with OpenResty Edge, and you can only access it via IP.

  [+] Do you want to configure ssl certificate and private key? [y/N] y
  [-] Please enter the path of ssl certificate file (like /etc/ssl/ssl.crt): /etc/ssl/ssl.crt
  [-] Please enter the path of ssl key file (like /etc/ssl/ssl.key): /etc/ssl/ssl.key
  

• Configure Database and Log Server Addresses：(If Database, Edge Admin, and Log Server use the same machine, you can use the default configuration).

  [+] Do you want to configure admin database and log server address (/usr/local/oredge-admin/conf/config.ini)? [y/N] y
  [-] Please enter the address of admin database (if admin database and admin use the same machine, no need to input.):
  [-] Please enter the address of log server (if log server and admin use the same machine, no need to input.): 54.112.79.32
  

  Please make sure that the current server can be connected to the IP entered.

• If successful, the following prompt will be displayed at the end.

  Install Edge admin successfully! login username: admin , password: xxxxxxxxxxx .
  

# 3.3.2 Verify the Installation

• You can also check if the process is started by using the following command.

  ps aux | grep oredge-admin
  

• You can also check if there is any abnormal information in Edge Admin’s logs. The log directory is /usr/local/oredge-admin/logs, you can get the latest log content by the following command.

  sudo ls -rt /usr/local/oredge-admin/logs/error* | tail -n1 | xargs -i sudo tail -n 50
  

At this point, Edge Admin is working properly, and you can access the Edge Admin via https://your_domain/.

If no certificate is configured before, the self-signed certificate we provide is used and can only be accessed through https://admin_ip/, and you also need to ignore the browser’s certificate error prompt to access it properly.

# 3.4 OpenResty Edge Log Server Database Installation

# 3.4.1 Installation

• The procedure is similar to the previous one, with the component Log Server Database selected during installation.

  [1] Edge Admin Database
  [2] Log Server Database
  [3] Edge Admin
  [4] Log Server
  [5] Edge Node
  Which component would you like to install? 2
  What you choose is: Log Server Database.
  

• If successful, the following prompt will be displayed at the end.

  Great! Init log server database successfully.
  

# 3.4.2 Verify the Installation

• You can also check if the process is started by using the following command.

  ps aux | grep openresty-postgresql12
  

• You can also check if there is any abnormal information in the Edge Admin Database log. The log directory is /var/postgres12/data/pg_log, you can get the latest log content by the following command.

  sudo ls -rt /var/postgres12/data/pg_log/* | tail -n1 | xargs sudo tail -n 50
  

# 3.5 OpenResty Edge Log Server Installation

The Log Server machine needs to expose two ports 12346 and 8089, port 12346 for communication with the Edge Node and 8089 for communication with the Edge Admin.

# 3.5.1 Installation

• The procedure is similar to the previous one, with the component Log Server selected during installation.

  [1] Edge Admin Database
  [2] Log Server Database
  [3] Edge Admin
  [4] Log Server
  [5] Edge Node
  Which component would you like to install? 4
  What you choose is: Log Server.
  

• Configure Database and Edge Admin addresses：(If Database, Edge Admin, and Log Server use the same machine, you can use the default configuration).

  [+] Do you want to configure pg and admin address (/usr/local/oredge-log-server/conf/config.ini)? [y/N] y
  [-] Please enter the address of log server database (if log server database and log server use the same machine, no need to input.):
  [-] Please enter the address of admin server (if admin and log server use the same machine, no need to input.): 45.121.32.78
  

  Please make sure that the current server can be connected to the IP entered.

• If successful, the following prompt will be displayed at the end.

  Install Edge Log Server successfully!
  
  

# 3.5.2 Verify the Installation

• You can also check if the process is started by using the following command.

  ps aux | grep oredge-log-server | grep -v grep
  

• You can also check if there is any abnormal information in Edge Admin’s logs. The log directory is /usr/local/oredge-log-server/logs, you can get the latest log content by the following command.

  sudo ls -rt /usr/local/oredge-log-server/logs/error* | tail -n1 | xargs -i sudo tail -n 50
  

# 3.6 OpenResty Edge Node Installation

# 3.6.1 Installation

• The procedure is similar to the previous one, with the component Edge Node selected during installation.

  [1] Edge Admin Database
  [2] Log Server Database
  [3] Edge Admin
  [4] Log Server
  [5] Edge Node
  Which component would you like to install? 5
  What you choose is: Edge Node.
  

• Configure Edge Admin and Log Server addresses.

  [+] Do you want to configure admin and log server address (/usr/local/oredge-node/conf/config.ini)? [y/N] y
  [-] Please enter the address of admin server:
  [-] Please enter the address of log server: 54.212.32.78
  

  Please make sure that the current server can be connected to the IP entered.

• If successful, the following prompt will be displayed at the end.

  Install Edge Node successfully!
  

# 3.6.2 Verify the Installation

• You can also check if the process is started by using the following command.

  ps aux | grep oredge-node
  

• You can also check if there is any abnormal information in Mpde’s logs. The log directory is /usr/local/oredge-node/logs, and you can get the latest logs with the following command.

  sudo ls -rt /usr/local/oredge-node/logs/error* | tail -n1 | xargs -i sudo tail -n 50
  

  If there is the following output in the log, it means the Edge Node has been successfully connected to Edge Admin, and you can approve the node to join in the Edge Admin management backend to use it normally. You can refer to Gateway Cluster.

  2021/11/16 14:37:38 [error] 6882#6882: *51983 [lua] privileged.lua:819: could not establish node identity: not yet approved, context: ngx.timer
  

At this point, OpenResty Edge deployment is complete.

# 3.7 Double OpenResty Edge Admin (Optional)

If you want to improve the availability of Edge Admin service, deploying two Edge Admin services as master-master may be a good choice.

• Follow step 3.3 above to install another Edge Admin.

• Modify the Edge Admin configuration

  # This file will not be automatically overwritten by subsequent upgrades, so be careful not to leave spaces at the beginning of lines
  sudo vim /usr/local/oredge-admin/conf/config.ini
  

  You need to modify the host field under the clone_admin section and use another Edge Admin service address as the configured value in both of the Edge Admin servers.

  Restart the Edge Admin service after modification.

  sudo systemctl start upgrade-oredge-admin
  

  The two Edge Admin services are in master-master mode now. Visiting any of the Edge Admins has the same effect.

• Modify the Edge Node configuration

  # This file will not be automatically overwritten by subsequent upgrades, so be careful not to leave spaces at the beginning of lines
  sudo vim /usr/local/oredge-node/conf/config.ini
  

  Modify the host2 field under the admin section of the configuration file and configure it to be the address of another Edge Admin.

  Restart the Edge Node service after modification.

  sudo systemctl start upgrade-oredge-node
  

  Edge Node will use host and host2 randomly (regardless of configuration order) and switch to the other Edge Admin service automatically when one Edge Admin is down.

# 4. Automated installation of OpenResty Edge

You can also use a non-interactive installation to install OpenResty Edge.

Example 1:

sudo bash openresty-edge-installer.sh -a install -c node -v 22.12.1 -m 192.168.10.1 -l 192.168.10.2

Install the 22.12.1 version of OpenResty Edge Node and modify the corresponding configuration of Edge Admin Host and Log Server Host in the configuration file.

Example 2:

sudo bash openresty-edge-installer.sh -a install -c admin -v 22.12.1 -d 192.168.10.3 -l 192.168.10.2 -s /tmp/cert.crt -k /tmp/key.crt

Install 22.12.1 version of OpenResty Edge Admin, modify the corresponding configuration of Database Host and Log Server Host in the configuration file, and configure the SSL certificate of Edge Admin Console to /tmp/cert.crt and /tmp/key.crt.

The openresty-edge-installer.sh script currently supports the following parameters:

    -a, --action                install, upgrade, downgrade, uninstall.
    -c, --component             admin, log-server, node, log-server-db, admin-db, rebuild, clean-db.
    -v, --version               22.6.1 when upgrade, install, or uninstall, 22.6.1-1 when downgrade.
    -p, --plus-version          use in downgrade, examples: 1.19.3.1.36-1.
    -d, --db-host               specify database host, which can be used when installing admin and log server.
    -m, --admin-host            specify admin host, which can be used when installing node.
    -s, --admin-ssl-cert-path   specify ssl cert path for admin console.
    -k, --admin-ssl-key-path    specify ssl key path for admin console.
    -i, --admin-ssl-skip        skip configuration of admin ssl certificate.
    -l, --log-server-host       specify log server host, which can be used when installing node and admin.
        --backup-db             if exist, will backup db when upgrade admin db.
    -h, --help                  help info.

# 5. Database Backup and High Availability (Optional)

We provide two ways to make sure data security. We strongly recommend using both methods to make sure data security.

Database Backup

Database High Availability

# 6. Getting Started

We provide online documents, and related blog posts and corresponding video tutorials.

# 7. More

• Uninstall OpenResty Edge

If you have any questions, please feel free to contact us.