Installation

SMON is deprecated and will be removed soon.
We recommend moving your monitoring to RMON.

For container deployments, see Docker Compose, Helm and process setup, or try the local HTTPS quick start.

For Kubernetes, install the published Helm chart from GHCR using the Helm deployment guide.

Roxy-WI 10.0 also supports Podman with native systemd Quadlet units, for rootful or rootless controller deployment.

OS support Install Roxy-WI with Podman Installation on CentOS/Red Hat Enterprise Linux/Oracle Linux Installation on Ubuntu Install Checker, Metrics, Port Scanner and Socket Installing SELinux policy

After the installation: configuring Roxy-WI Database settings Apache settings Generate SALT

OS support

Roxy-WI supports the
following OSes:

EL7 (RPM installation and manual installation). It must be "Infrastructure Server" at least. x86_64 only.
EL8 (RPM installation and manual installation). It must be "Infrastructure Server" at least. x86_64 only.
EL9 (RPM installation and manual installation). It must be "Infrastructure Server" at least. x86_64 only.
Ubuntu (DEB installation and manual installation). x86_64 only.
Other Linux distributions (manual installation only). x86_64 only.
At least Python 3.9 for Ubuntu and Python 3.11 for EL

Install Roxy-WI with Podman

From Roxy-WI 10.0, the controller can run on Podman with native Quadlet units. The profile includes Web, Scheduler, Service Events, Operations, RabbitMQ, SQLite and a local HTTPS endpoint, with persistent data and encrypted Podman secrets.

Prepare a Linux host with systemd, cgroup v2, Python 3.10+, Podman 4.9+ with Quadlet, and an encryption-capable GPG key for the Podman owner. Follow the host and secret-storage requirements before starting.

From a Roxy-WI 10.0 source checkout, run these commands as the rootless owner. Replace GPG_FINGERPRINT with that account's full key fingerprint:

python3 podman/deploy.py prepare --build --gpg-fingerprint GPG_FINGERPRINT
python3 podman/deploy.py start
python3 podman/deploy.py password

Open https://localhost:8443 and sign in as admin with the generated password. For system units, use sudo consistently and root's GPG key. The default endpoint binds to loopback and uses a local evaluation CA.

See the Podman controller guide for remote access, startup after reboot, upgrades and recovery. This profile does not automatically migrate an existing package or Compose installation.

To install HAProxy, NGINX or Apache containers on managed servers, follow managed Docker and Podman services.

Installation on:

Installation on CentOS/Red Hat Enterprise Linux/Oracle Linux

To use the Roxy-WI services, please make a donation to support our project on Boosty. We will send you the access credentials by email shortly. You can find current prices here. We will not be able to do our work without voluntary contributions. Any donations to support our work are greatly appreciated. Every gift counts!

Installation information for different operating systems can be found here. To install Roxy-WI on CentOS/Red Hat Enterprise Linux/Oracle Linux, follow the steps below.

Retrieve the signed RPM configuration files (run this command as sudo):


sudo yum install https://repo.roxy-wi.org/roxy-wi-release-7-2-5.noarch.rpm

or

sudo yum install https://repo1.roxy-wi.org/roxy-wi-release-7-2-5.noarch.rpm

Install the extra repository:

                                        
                                        sudo yum install epel-release

Install Roxy-WI and services:


# Disable SELinux in config /etc/selinux/config and run command:

sudo setenforce 0

# Install Roxy-WI and services:
sudo yum install roxy-wi roxy-wi-smon roxy-wi-keep_alive roxy-wi-portscanner

Open the following link in your browser: https://your_ip/.

Use the default credentials: login - admin, password - admin.

If you are going to use Roxy-WI to manage multiple servers in production, we recommend using MySQL. Read here how to set up MySQL.

Do not forget to generate a new SALT. Read here how to do this.

Installation on Ubuntu

DEB packages are only available for the following Linux distributions: Ubuntu (Bionic, Focal, Groovy, Hirsute, Impish, Jammy, Kinetic, Lunar, Mantic). Installation information for different operating systems can be found here. Follow the steps below to install Roxy-WI on Ubuntu.

Add the Roxy-WI repository to your source list:

                                    sudo echo \
                                      "deb [arch=amd64, trusted=yes] https://repo.roxy-wi.org/ubuntu \
                                      $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/roxy-wi.list > /dev/null

Run the following commands:

sudo apt-get update
sudo apt-get install roxy-wi roxy-wi-smon roxy-wi-portscanner roxy-wi-keep-alive

Install additional Python packages if they are not installed:

                        pip3 install setuptools_rust --break-system-packages
                        pip3 install paramiko-ng --break-system-packages

Create a Roxy-WI configuration file in the /etc/roxy-wi/roxy-wi.cfg directory:

[main]
# Path to the files destination
fullpath = /var/www/haproxy-wi
log_path = /var/log/roxy-wi
lib_path = /var/lib/roxy-wi
# Change secret_phrase to 32 url-safe base64-encoded
secret_phrase = _B8avTpFFL19M8P9VyTiX42NyeyUaneV26kyftB2E_4=

[configs]
# Folders for configs
haproxy_save_configs_dir = ${main:lib_path}/configs/hap_config/
keepalived_save_configs_dir = ${main:lib_path}/configs/kp_config/
nginx_save_configs_dir = ${main:lib_path}/configs/nginx_config/
apache_save_configs_dir = ${main:lib_path}/configs/apache_config/

[mysql]
# By default Sqlite DB is used
enable = 0
mysql_user = roxy-wi
mysql_password = roxy-wi
mysql_db = roxywi
mysql_host = 127.0.0.1
mysql_port = 3306

Open the following link in your browser: https://your_ip/.

Use the default credentials: login - admin, password - admin.

If you get the "Internal error" after installation, install all requirements via pip3.

If you are going to use Roxy-WI to manage multiple servers in production, we recommend using MySQL. Read here how to set up MySQL.

Do not forget to generate a new SALT. Read here how to do this.

Install Checker, Metrics, Port Scanner and Socket

Checker 5, Metrics 4, Port Scanner 2 and Socket 2 are optional, independently running services. They require RabbitMQ and an active User plan or higher. Roxy-WI itself can be installed without them.

Configure RabbitMQ before starting the services. Roxy-WI and every worker must use the same RabbitMQ virtual host and credentials that have access to it.

Install package-managed workers on the Roxy-WI host or on separate worker hosts:

# EL/RHEL-compatible systems
sudo dnf install roxy-wi-checker roxy-wi-metrics roxy-wi-portscanner roxy-wi-socket

# Debian/Ubuntu
sudo apt update
sudo apt install roxy-wi-checker roxy-wi-metrics roxy-wi-portscanner roxy-wi-socket

These packages do not depend on the Roxy-WI package. They create dedicated unprivileged users, install their Python dependencies into service-owned directories and enable roxy-wi-checker.service, roxy-wi-metrics.service, roxy-wi-portscanner.service and roxy-wi-socket.service. Allow outbound HTTPS access to the configured Python package index during installation.

On the Roxy-WI host, the default auto mode reuses RabbitMQ settings from the local Roxy-WI database. On a worker-only host, edit the corresponding /etc/roxy-wi/checker.env, metrics.env, portscanner.env or socket.env: set *_USE_ROXYWI_RABBITMQ_SETTINGS=0 and provide the service's *_RABBITMQ_HOST, port, vhost, user and password. Then run the systemctl enable --now commands above. A fresh standalone package is enabled but waits for this configuration before it is started.

Socket additionally needs a read-only copy of the Roxy-WI JWT public key. The Roxy-WI private key must never be copied to a worker host.

# Run only on the Roxy-WI host
sudo systemctl enable --now roxy-wi-scheduler roxy-wi-service-events

# Run on each worker host after its env-file is configured
sudo systemctl enable --now roxy-wi-checker
sudo systemctl enable --now roxy-wi-metrics
sudo systemctl enable --now roxy-wi-portscanner
sudo systemctl enable --now roxy-wi-socket

Run the workers on separate Docker or Kubernetes hosts:

Checker image: ghcr.io/roxy-wi/roxy-wi-checker:5.0.0
Metrics image: ghcr.io/roxy-wi/roxy-wi-metrics:4.0.0
Port Scanner image: ghcr.io/roxy-wi/roxy-wi-portscanner:2.0.0
Socket image: ghcr.io/roxy-wi/roxy-wi-socket:2.0.0

Containers do not read the Roxy-WI database. Pass the matching CHECKER_RABBITMQ_*, METRICS_RABBITMQ_*, PORTSCANNER_RABBITMQ_* or SOCKET_RABBITMQ_* environment variables. Socket also requires the Roxy-WI JWT public key. Use Secrets rather than placing passwords or keys in Compose files or Kubernetes manifests.

One Checker, Metrics or Port Scanner replica may use its persistent SQLite volume. Multiple replicas must share a dedicated MySQL/MariaDB schema for that service. Do not point a worker at the Roxy-WI application schema.

Monitored server addresses and HAProxy, NGINX or Apache statistics endpoints must be reachable from the worker host. Use a routable private IP or DNS name instead of 127.0.0.1 when the worker runs on another server.

See the Checker, Metrics, Port Scanner and Socket pages for service-specific configuration. For migration from older master processes, follow the update guide.

Installing the SELinux policy

When you install RPM packages, the SELinux policy is automatically installed. If you have problems configuring the SELinux policy, install the following package:

                                    sudo yum install roxy-wi-selinux

You can also just disable SELinux.

After the installation: Configuring Roxy-WI

After installing Roxy-WI, edit the /etc/roxy-wi/roxy-wi.cfg configuration file. The default configuration is shown below:

                                    [main]
                                    # Path to the files destination
                                    fullpath = /var/www/haproxy-wi
                                    log_path = /var/log/roxy-wi
                                    lib_path = /var/lib/roxy-wi
                                    # Change secret_phrase to 32 url-safe base64-encoded
                                    secret_phrase = _B8avTpFFL19M8P9VyTiX42NyeyUaneV26kyftB2E_4=
                                    
                                    [configs]
                                    # Folders for configs
                                    haproxy_save_configs_dir = ${main:lib_path}/configs/hap_config/
                                    keepalived_save_configs_dir = ${main:lib_path}/configs/kp_config/
                                    nginx_save_configs_dir = ${main:lib_path}/configs/nginx_config/
                                    apache_save_configs_dir = ${main:lib_path}/configs/apache_config/
                                    
                                    [mysql]
                                    # By default Sqlite DB is used
                                    enable = 0
                                    mysql_user = roxy-wi
                                    mysql_password = roxy-wi
                                    mysql_db = roxywi
                                    mysql_host = 127.0.0.1
                                    mysql_port = 3306

Database settings

The default database used by Roxy-WI is SQLite. If you want to use MySQL, make the following changes to the configuration file:

                                [mysql]
                                #Enable MySQL DB. Default will be used Sqlite DB. Default disable
                                enable = 1
                                mysql_user = roxywi
                                mysql_password = roxy-wi
                                mysql_db = roxywi
                                mysql_host = 127.0.0.1

After editing the configuration file, create the Roxy-WI database on your MySQL server:

                                MariaDB [(none)]> create user 'roxy-wi'@'%';
                                MariaDB [(none)]> create database roxywi;
                                MariaDB [(none)]> grant all on roxywi.* to 'roxy-wi'@'%' IDENTIFIED BY 'roxy-wi';
                                MariaDB [(none)]> grant all on roxywi.* to 'roxy-wi'@'localhost' IDENTIFIED BY 'roxy-wi';

After creating the database, run the create_db.py script. The script is located in the /var/www/haproxy-wi folder.

If you are going to use Roxy-WI to manage multiple servers in production, we recommend using MySQL.

After this, run the python3 migrate.py init command to create the migrations table in the database, then run the migration with the python3 migrate.py migrate command.

Configuring Apache

If you want to use a custom domain name, make changes to the Apache configuration file for Roxy-WI:

                                    sudo vi /etc/httpd/conf.d/roxy-wi.conf

If you want to enable redirection from port 80 to port 443, add the following lines to your configuration file:

                                    <VirtualHost *:80>
                                            ServerName my_domain.local
                                            Redirect permanent "/" "https://my_domain.local/"
                                    
                                    </VirtualHost>

Find the following lines and replace "roxy-wi.example.com" with your domain name:

                                    <VirtualHost *:443>
                                        ...
                                        ServerName my_domain.local
                                        ...
                                    </VirtualHost>

If you want to use custom certificates, edit the following lines:

                                    <VirtualHost *:443>
                                        ...
                                        SSLEngine on
                                        SSLCertificateFile /var/www/haproxy-wi/app/certs/haproxy-wi.crt
                                        SSLCertificateKeyFile /var/www/haproxy-wi/app/certs/haproxy-wi.key
                                        ...
                                    </VirtualHost>

Generate SALT

Starting with version 7.1.2, Roxy-WI encrypts SSH passwords and SSH passphrases. To ensure that no one but you can decrypt your passwords, generate your own salt (run python3 for this) and put it in /etc/roxy-wi/roxy-wi.cfg:

                                from cryptography.fernet import Fernet
                                
                                key = Fernet.generate_key()
                                print(key)