Quick Installation of the Operavix Server Component

• Installing the Operavix Application on Windows
• Installing the Operavix Application on Linux
• Installing the ClickHouse Analytical DBMS
• Connecting the Operavix Server to the ClickHouse Analytical DBMS

Installing the Operavix Application on Windows

The Operavix application can be installed on a server running Windows Server 2012 R2 (x64) or later.

Perform the following steps:

1. Run the provided .exe file on the server with local administrator privileges. The application installer window will open.
2. Review the End User License Agreement, accept it by checking the box next to I agree to the End User License Agreement.
3. Click Install.
4. During installation, a prompt may appear to create an inbound rule for Windows Firewall. Allow the rule to be created.
5. After installation completes, click Finish.
6. The default browser will open a page for creating the system administrator account.
7. Fill in the fields on the page and click Apply and sign in. The specified credentials will be used by the first system administrator to sign in to the web interface.
8. After successful entry, the system activation key page will open. Enter the license key provided to you and click Activate.
9. Upon successful activation, the system web interface will open. The application is installed and ready for further configuration.

Configuring the Operavix Application on Windows to Use the HTTPS Protocol

After installation, the Operavix application communicates with the web interface and monitoring agents over HTTP. To configure secure communication over HTTPS, perform the following steps:

1. Prepare an SSL certificate and private key for the server where the application is installed in the form of a .pfx file (PKCS#12). It is acceptable to include CA certificates in the .pfx file. Ensure this server certificate is trusted on computers where monitoring agents will be installed and where the web interface will be accessed. To obtain a certificate, contact your organization’s Public Key Infrastructure (PKI) administrators.
2. On the server, stop the Operavix service: press Win+R, open services.msc, right-click Operavix in the window that opens, and select Stop.
3. Launch a text editor (e.g., Notepad) as an administrator and edit the application web server configuration file: C:\ProgramData\Operavix\config\com.operavix.subsystem.frontend.json. We recommend creating a backup of the file before editing.
4. Make the following changes to the file:
   • "protocol":"https" — enables HTTPS
   • "port":443 — specify the port on which the web server will operate
   • "ssl_cert_store_password":"password" — password for the .pfx file. If the password is empty, specify ""
   • "ssl_cert_store":"C:\\ProgramData\\Operavix\\certs\\file.pfx" — path to the .pfx file. Backslashes must be escaped with an additional backslash
   • "url" — used by the system to generate all inbound links (e.g., password reset and invitation links in email messages)
5. Save the file.
6. Start the Operavix service.
7. Verify web server accessibility over HTTPS on the specified port. If issues occur after startup, check the log file: C:\ProgramData\Operavix\logs\main.log.

Specifying the Amount of RAM Available to the Operavix Application on Windows

The maximum amount of server RAM (memory) that the Operavix application can use is strictly defined in the service startup parameters.

To change the allocated RAM for the Operavix service, perform the following steps:

1. Open the Registry Editor as an administrator.
2. In the Registry Editor, navigate to the key: Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Operavix.
3. Double-click ImagePath.
4. In the Value Data field, change the -Xmx2G parameter to the desired value in gigabytes (e.g., -Xmx8G to allocate 8 GB of memory).
5. Save the changes and restart the Operavix service via the Services console or Task Manager.

Installing the Operavix Application on Linux

To install the Operavix application on Linux, perform the following actions:

1. Install Docker on the server by following the official documentation: https://docs.docker.com/engine/install/.
2. Download the provided Docker image archive to the target server.
3. Extract the archive and load it into the local Docker image store.
   $ gunzip operavix_docker_app_d230809.tar.gz
   

   # docker load < operavix_docker_app_d230809.tar
   

   Note: The image version is provided as an example. When using the command, replace the version with the one you are installing.
4. Create Docker volumes for persistent storage of application data.
   # docker volume create operavix-app-data
   

   # docker volume create operavix-app-log
   

Running the Operavix Application with HTTP

To run a container with the application operating over HTTP, execute the following command:

# docker run -d --name operavix-app \
--mount source=operavix-app-data,target=/var/lib/operavix/data/ \
--mount source=operavix-app-log,target=/var/log/operavix/ \
-p 0.0.0.0:8010:8010 -d --restart=always \
dockerhub.office.operavix.com/operavix/operavix_app:d230809

Running the Operavix Application with HTTP (Swarm)

To run a container with the application operating over HTTP using Swarm, perform the following steps:

1. Initialize a local Docker Swarm.
   # docker swarm init --advertise-addr 127.0.0.1:2377 --listen-addr 127.0.0.1:2377
   

2. Create a service.
   # docker service create --name operavix-app \
   --mount type=volume,src=operavix-app-data,target=/var/lib/operavix/data/ \
   --mount type=volume,src=operavix-app-log,target=/var/log/operavix/ \
   -e JVM_MAX_MEMORY='4G' \
   --publish published=8010,target=8010,mode=host \
   --limit-memory 30G \
   --limit-cpu 2 \
   --restart-max-attempts 5 \
   --restart-condition "on-failure" \
   dockerhub.office.operavix.com/operavix/operavix_app:d230809
   

   Note: The image version is provided as an example. When using the command, replace the version with the one you are installing.

Running the Operavix Application with HTTPS (Swarm)

To run a container with the application operating over HTTPS using Swarm, perform the following steps:

1. Initialize Docker Swarm.
   # docker swarm init --advertise-addr 127.0.0.1:2377 --listen-addr 127.0.0.1:2377
   

2. Create secrets.
   # docker secret create operavix_app_https_certificate ${PATH_FILE}
   

   # echo -n "${PASSWORD_CERTIFICATE}" | docker secret create operavix_app_https_certificate_password -
   

   Explanation:
   • ${PATH_FILE} — full path to the certificate and private key file
   • ${PASSWORD_CERTIFICATE} — password for the certificate file
3. Create a service.
   # docker service create --name operavix-app \
   --secret operavix_app_https_certificate \
   --secret operavix_app_https_certificate_password \
   --mount type=volume,src=operavix-app-data,target=/var/lib/operavix/data/ \
   --mount type=volume,src=operavix-app-log,target=/var/log/operavix/ \
   --publish published=443,target=8010,mode=host \
   --restart-max-attempts 5 \
   --restart-condition "on-failure" \
   -e JVM_MAX_MEMORY='4G' \
   -e FE_URL="https://server-name.domain.com  " \
   -e FE_CORS_POLICY="*" \
   operavix/operavix_app:d230809
   

   Advice

   • The image version is provided as an example. When using the command, replace the version with the one you are installing.
   • We recommend using the standard HTTPS port — 443. You may specify a different port if needed.
4. In the JVM_MAX_MEMORY variable, specify the maximum amount of RAM (in gigabytes) that the Operavix application can use. We recommend setting this to 60–90% of the server’s available RAM. In the FE_URL variable, specify the working URL that will be used to access the web interface. In the FE_CORS_POLICY variable, specify * to allow cross-origin requests from any site. To restrict access, list the URLs that require cross-origin communication, separated by commas (e.g., "https://operavix.com , https://operavix.pt ").
5. The application is now running. Open https://<server-fqdn>/ in a web browser to create the system administrator account.

If the page does not open:

• Verify that the container is running:
  # docker ps
  

• Check the application logs:
  # docker service logs -f operavix-app
  

• Ensure connectivity from the browser machine to the Operavix server (e.g., using telnet).

Installing the ClickHouse Analytical DBMS

To install the ClickHouse analytical DBMS, you need a Linux-based server capable of running Docker 17.06 or later. Additionally, the Linux server(s) where ClickHouse will be installed must have a kernel version of:

• 3.15 or higher when using the EXT4 filesystem
• 4.0 or higher when using the XFS filesystem

If the OS kernel version does not meet these requirements, many system features may be unavailable or unstable.

Preparing a Certificate and Private Key for the ClickHouse DBMS Server

To enable secure HTTPS communication between the Operavix application and the ClickHouse DBMS, prepare an SSL certificate and private key for the server where the DBMS will be installed. The certificate file must have a .crt extension, and the key file must have a .key extension in PEM format.

To obtain a certificate, contact your organization’s Public Key Infrastructure (PKI) administrators.

You may also use a self-signed certificate. Below is an example OpenSSL command to generate one on a Linux-based OS:

$ openssl req -x509 -nodes -newkey rsa:2048 -days 365 -keyout key.key -out cert.crt \
-subj "/C=RU/ST=./L=./O=./OU=./CN=server-name.domain.com/emailAddress=." \
-addext "subjectAltName = IP:1.1.1.1,DNS:server-name.domain.com"

Starting the ClickHouse DBMS Docker Service

The ClickHouse DBMS is distributed as a Docker image. To install the DBMS container on a Linux server, perform the following steps:

1. Install Docker on the server by following the official documentation: https://docs.docker.com/engine/install/.
2. Download the provided Docker image archive to the server.
3. Extract the archive and load the image into the local Docker store.
   # gunzip operavix_clickhouse-23.3.2.37.tar.gz
   

   # docker load < operavix_clickhouse-23.3.2.37.tar
   

   Note: The image version is provided as an example. When using the command, replace the version with the one you are installing.
4. If Docker Swarm has not yet been initialized on the server, run the initialization command.
   # docker swarm init --advertise-addr 127.0.0.1:2377 --listen-addr 127.0.0.1:2377
   

5. Create secrets with ClickHouse DBMS administrator credentials.
   # echo -n "operavix_user" | docker secret create operavix_app_user -
   

   # echo -n "b5w4GDSg36" | sha256sum | awk '{print $1}' | docker secret create operavix_app_user_password_hash -
   

6. Create secrets with ClickHouse DBMS read-only user credentials.
   # echo -n "operavix_read_user" | docker secret create operavix_external_user -
   

   # echo -n "m26dhdhFdgj" | sha256sum | awk '{print $1}' | docker secret create operavix_external_user_password_hash -
   

7. Create secrets with the SSL certificate and key.
   # docker secret create operavix_clickhouse.crt cert.crt
   

   # docker secret create operavix_clickhouse.key key.key
   

   # openssl dhparam 4096 | docker secret create operavix_clickhouse_dhparam.pem -
   

8. Create Docker volumes for persistent container data storage.
   # docker volume create operavix-clickhouse
   

   # docker volume create operavix-clickhouse-log
   

9. Create a service.
   # docker service create --name operavix-clickhouse \
   --secret operavix_app_user \
   --secret operavix_app_user_password_hash \
   --secret operavix_external_user \
   --secret operavix_external_user_password_hash \
   --secret operavix_clickhouse_dhparam.pem \
   --secret operavix_clickhouse.crt \
   --secret operavix_clickhouse.key \
   --publish published=8123,target=8123,mode=host \
   --mount type=volume,src=operavix-clickhouse,target=/var/lib/clickhouse/ \
   --mount type=volume,src=operavix-clickhouse-log,target=/var/log/clickhouse-server \
   --restart-max-attempts 5 \
   --restart-condition "on-failure" \
   dockerhub.office.operavix.com/operavix/operavix-clickhouse:23.3.2.37
   

   Note: The image version is provided as an example. When using the command, replace the version with the one you are installing.

If the service starts successfully, the command output will be: verify: Service converged.

To verify that the DBMS is running stably, open https://<server-address>:8123/ping in a browser or use the command curl https://<server-address>:8123/ping. If configured correctly, the response will be: OK.

If no response appears:

• Check that the container is running.
  # docker ps
  

• Review the application logs.
  # docker service logs -f operavix-clickhouse
  

• Ensure network connectivity to the server is open.

Check for errors in the startup steps and try recreating the service. To remove a non-working service, use the command docker service rm operavix-clickhouse.

Connecting the Operavix Server to the ClickHouse Analytical DBMS

After installing the Operavix application and ClickHouse DBMS, configure their connection. Perform the following steps:

1. Click the gear icon in the lower left corner and open the Data Storages section.
2. On the Data Storages page, select the desired connection and click it. The connection settings page will open.
3. Specify the ClickHouse DBMS connection parameters according to your server configuration:
   • Name — a convenient name for the server connection
   • Host — FQDN of the ClickHouse server
   • Port — default is 8123
   • Username — DBMS administrator login
   • Password — DBMS administrator password
   • SSL (On/Off) — enable if ClickHouse uses HTTPS. When enabled, you can upload the root certificate that signed the ClickHouse server certificate (or the self-signed certificate, if used)
   • Authentication — select the authentication method for connecting to ClickHouse. Standard authentication is used by default, but pass-through authentication (login/password) is also available in beta
   • Session time (minutes) — number of minutes allocated for storing a session per individual SQL query. We recommend keeping the default value
   • Memory limit per script query (MB) — maximum RAM allocated by the ClickHouse server for a single SQL query sent from a script. Default: 4112 MB
   • Memory limit per dashboard query (MB) — maximum RAM allocated by the ClickHouse server for a single SQL query initiated from a dashboard. Default: 1024 MB
   • Concurrent connections — allowed number of open sessions between the Operavix server and this ClickHouse connection. We recommend keeping the default value
   • Execution queue size — limit on the number of SQL queries waiting for execution. We recommend keeping the default value
4. Click Test connection to verify settings.
5. If the connection test succeeds, click Save. The connection is established.

If the connection test fails, consult the Operavix application log:

• On Windows: C:\ProgramData\Operavix\logs\main.log
• On Linux: var/lib/docker/volumes/operavix-app-log/_date/main.log or use the command docker service logs operavix-app