OpenResty XRay™ On-Premise Deployment on docker-compose

# Name

Installation and deployment guide for the On-Premise (docker-compose) version of OpenResty XRay.

# Table of Content

• Overview
• Installation
  • Console Server
  • Agent
• Basic Ops

# Overview

OpenResty XRay (XRay) On-Premises edition consists of two parts: Console Server and Agent.

The Console Server runs in the docker container, managed by docker-compose, all services of the Console Server are on the single machine, and the Agent runs on the target machine.

XRay Console Server consists of there parts:

• OpenResty XRay Console:
  • xray-console: web service of the console, providing a web UI based dashboard.
  • xray-console-pg: PostgreSQL database for xray-console.
• OpenResty XRay BuildBox:
  • build-box-[dist]: the back-end service for building xray tools, where dist represents the corresponding Linux distro.
  • xray-tenant-db: provide query API for xray-console and build-box-[dist], which will query first local tenant-db service and then remote pkg-db The service will only request queries to our remote public pkg-db, and no data will be uploaded to our public pkg-db
  • xray-tenant-db-pl: provide API for private package info.
  • xray-tenang-db-pg: postgresql database for xray-tenant-db-pl.

# Installation

# Console Server

# 1. Hardware requirements

• Network: Can access the Internet, can be accessed by target machine, no public network address or exposed listening port required.
• RAM: >= 4G, and 16G is recommended.
• CPU: >= 2 Cores and 4 Cores are recommended.
• Dist: >= 500G, and 1TB+ is recommended; persistent data is under /data directory.

Note: Based on our experience, the data sampled by a single agent node is about 10G for 30 days.

# 2. Public Network Accessing

The Console Server service requires the public network to access our public pkg-db API. The pkg-db service provides query and download services for common-use Linux distribution repositories, making OpenResty XRay support for analysis of many open-source software and libraries.

# 3. Linux Distributions

We’d recommend to use those Linux distributions that provide docker engine packages as we are using docker service. Here is a list of these distributions:

• ubuntu >= 16.04
• centos >= 7 (kernel >= 3.10.0-514)
• fedora >= 28
• debian >= 8
• RHEL == 7

# 4. docker and docker-compose

Please refer to https://docs.docker.com/engine/install/ for the installation guide of docker.

Please keep in mind to start the docker service after the docker installation

Please refer to https://docs.docker.com/compose/install/ for the installation guide of docker-compose.

# 5. certificate deployment (optional) and hostname setting (required)

If you need to use a custom certificate, you need to perform this step, or the Console Server will use the built-in certificate (please ignore browser warnings when accessing the dashboard)

Copy XRay server site certificate files into /data/orxray-console/cert/ssl.crt and /data/orxray-console/cert/ssl.key; the purpose of these certificate files are:

• Access XRay Console Dashboard through the HTTPS protocol.
• Security communication between Agent and Console Server.

Replace the domain name of console

To access the console using a custom domain name, you need to modify the services -> xray-console -> environment -> CONSOLE_HOST field of the docker-compose.yml file as follows:

# ...

services:
  # ...
  xray-console:
    # ...
    environment:
      # ...
      CONSOLE_HOST: example.com

You can also use the sed command:

sed -i 's/\bCONSOLE_HOST:\s*\S\+/CONSOLE_HOST: example.com/g' /opt/orxray/docker-compose.yml

# deployment and startup

Login to our registry with the username and password of docker-registry provided in the email:

$ docker login registry.openresty.com

We use the docker-compose.yml file provided by our email attachments as a template of configure file, it is recommended to put it to /opt/orxray/docker-compose.yml.

Startup:

$ cd /opt/orxray && docker-compose config -q && docker-compose up -d

Check the status:

$ cd /opt/orxray && docker-compose ps

Now the Console Server has been deployed and started, and You may use the domain name you just configured to access it.

# Agent

The agent side runs on the target machine; after installation, the agent side will communicate with the Console Server deployed in previous steps; the agent’s installation itself also cooperated with server-side:

Access your dashboard in your browser, and login with the initial username and password from the email (you may change the password after the first login). You’ll be greeted with an installation guide after login. Follow the installation guide to install the agent on the target machine.

# Basic Ops

# Console Server logs

$ docker-compose -f /opt/orxray/docker-compose.yml logs -p orxray -t

# test the docker-compose.yml

$ docker-compose -f /opt/orxray/docker-compose.yml config -p orxray -q

# service upgrade

Backup your docker-compose.yml first:

$ cp /opt/orxray/docker-compose.yml /opt/orxray/docker-compose.yml.bak

Use the docker-compose.upgrade.yml from email, and then:

$ cp docker-compose.upgrade.yml /opt/orxray/docker-compose.yml
$ cd /opt/orxray && docker-compose config -q && docker-compose up -d

# Error: ’tenant does not exist'

If you access the console with a browser and it says, “This tenant does not exist”, check if the access domain or IP matches the value of the CONSOLE_HOST variable in docker-compose.yml.

If the access address is http://xray.example.com and the value of CONSOLE_HOST is not xray.example.com, you will be prompted with this message.