This documentation applies to Roxy-WI 9.1 and later.
Roxy-WI is a self-hosted web interface for HAProxy, NGINX, Apache, Keepalived and Corosync/Pacemaker. Connect existing servers, review configuration changes, coordinate deployments and follow service health from one place. Built for operators and teams managing proxies and HA clusters across multiple servers and environments.
Try the live demo · Get started · Documentation · Plans & support
Current demo interface with worker health and recent logs. Click a service status to inspect its diagnostics.
| Your task | How Roxy-WI helps |
|---|---|
| Review changes before touching production | Compare configuration differences, validate candidates, require approval and keep an audit trail with Change Center. |
| Coordinate a deployment across HA nodes | Choose canaries and batches, check each target, pause between stages and recover or roll back failed changes. |
| Choose and operate your HA technology | Use Keepalived/VRRP or Corosync/Pacemaker with resource management, quorum witnesses and fencing. |
| Review HA readiness | Audit Keepalived and Pacemaker with per-node quorum/witness evidence, fencing configuration, declared failure domains and separately labelled test records. |
| Hand a node over for maintenance | Check quorum and placement, obtain approval, verify drain and return from HA clusters → Actions → Node maintenance. |
| Bring existing infrastructure into one interface | Connect servers over SSH; manage HAProxy, NGINX, Apache and Keepalived configurations and service actions. |
| Adopt an existing Linux HA cluster | Discover Corosync/Pacemaker nodes, verify their identities and configuration, and register the cluster while preserving its running configuration. |
| Choose a managed component runtime | Install HAProxy, NGINX, Apache or a standalone quorum witness with Native/Docker/Podman choices, or adopt existing containers with an explicit engine and owner. Podman Debian/EL VM qualification is pending. |
| Give the right people access | Organize servers into groups, assign roles and service permissions, and integrate OIDC or LDAP authentication. |
| Keep service health visible | Inspect backends and logs; add monitoring, traffic metrics and notifications as your needs grow. |
| Diagnose a published request | Inspect DNS, VIP/listener, TCP, TLS/SNI and candidate backends with bounded, configuration-derived probes and saved evidence. |
| Manage certificates and configuration history | Issue Let's Encrypt certificates or synchronize CertWarden certificates through provider connectors, including Pacemaker member targets; retain configuration versions and configure backup destinations. |
Some capabilities require a subscription. Change Center requires Premium; see feature availability before planning an evaluation.
See the HAProxy configuration workspace
Search configuration sections, switch to source view and edit through a form or text editor, depending on how the section was created.
Change Center keeps the candidate, review decision and target results together. Creating a draft does not replace the running configuration.
flowchart LR
A[Create a draft] --> B[Review the diff]
B --> C[Validate targets]
C --> D[Approve if required]
D --> E[Deploy in stages]
E --> F[Inspect results and drift]
E --> G[Rollback on failure]
Read the Change Center guide for canary rollouts, manual promotion, per-node results and recovery.
For a browser-only look, open the live demo with
admin / admin. It is a shared demonstration environment that resets hourly.
Use demonstration data only.
Install Linux packages: see deployment platforms and installation.
Try Roxy-WI locally: use the Compose quick start below.
It builds this checkout, starts the application and background workers, and exposes
the interface only at https://localhost:8443.
Requirements: Git, Python 3.10+, Docker with Linux containers, and Docker Compose 2.24.4+.
git clone https://github.com/roxy-wi/roxy-wi.git
cd roxy-wi
python3 docker/quickstart.py start
python3 docker/quickstart.py passwordOpen https://localhost:8443, accept the local evaluation certificate, and sign
in as admin with the generated password. Secrets and application data persist
between starts. The first build downloads application dependencies.
Continue with your first server, or read the full quick-start guide for status, logs and stopping.
| Environment | Entry point |
|---|---|
| Linux packages | Installation and update guide |
| Local evaluation | Compose quick start with SQLite and local HTTPS |
| Compose for your infrastructure | Deployment guide, including MariaDB, HTTPS and persistent storage |
| Podman on a Linux host | Native Quadlet controller deployment, with system or rootless user units, GPG-encrypted Podman secrets, SQLite and local HTTPS; awaiting Debian/EL VM qualification |
| Kubernetes | Published Helm chart, deployment guide and chart source |
The chart is published at oci://ghcr.io/roxy-wi/roxy-wi-charts.
Version 10.0 uses the ghcr.io/roxy-wi/roxy-wi:10.0 application image
by default. Prepare roxy-wi-values.yaml using the
Helm deployment guide,
including application secrets, RabbitMQ, persistent storage, database settings
and HTTPS ingress, then install:
helm upgrade --install roxy-wi oci://ghcr.io/roxy-wi/roxy-wi-charts \
--version 10.0 --namespace roxy-wi --create-namespace \
--values roxy-wi-values.yaml --wait --wait-for-jobs --timeout 10mRabbitMQ and an optional external MariaDB/MySQL database are provisioned separately. SQLite is the chart default for one Web replica. For an existing installation, follow the Helm update procedure before running an upgrade.
Choose Keepalived or Corosync / Pacemaker in HA Cluster. Use the Services → Corosync / Pacemaker submenu for cluster status, resources, configuration, quorum, logs, monitoring and history. HA cluster → Create Corosync cluster opens a dialog for creating a new cluster, adding an existing cluster or preparing a standalone witness.
- Provision supported Linux nodes or adopt a running cluster after reviewing discovered membership and configuration.
- Discover installed resource agents, configure resources and fencing devices, and define ordering and colocation constraints through web forms.
- Review CIB drafts, validate and simulate changes, apply digest-checked patches, and keep encrypted configuration history. Control nodes and resources from the UI.
- Configure an independent TLS quorum witness, installed natively or in Docker, and use reviewed membership, witness migration and recovery workflows.
- Install the HA Cluster Exporter, inspect metrics and diagnostics, and manage daemon Auto Start policies with safeguards for Pacemaker-owned proxy services.
Corosync provides cluster membership and quorum; Pacemaker coordinates resources and recovery. Configure and test fencing to isolate an unreachable member before recovering exclusive resources. Application data replication is configured separately.
Corosync/Pacemaker support was merged in #440. Until it is included in a published release, use a source checkout containing that merge.
See the Corosync and Pacemaker guide for permissions, Operations requirements and recovery boundaries. The HA support matrix distinguishes tested platforms, apt/dnf installation profiles, Docker workflows and SYN-flood settings. All repository guides are indexed in docs.
See the Corosync/Pacemaker workspace
Running lab interface with example addresses and names. See the screenshot notes and verification record for capture details, tested Debian/Rocky versions and qualification limits.
Enable Use multiple configuration files in the settings of the HAProxy service on the selected server. It is disabled by default. Roxy-WI reads the ordered configuration sources from systemd (including environment files and overrides) or Docker, and compares them with the running HAProxy process when available. There is no separate argument list to maintain in Roxy-WI.
The settings panel shows detected files and directories. If only the main file
is configured, it explains how to add a directory with -f to systemd or the
container command and provides a Check again button. Permission, connectivity,
missing-path and unsupported-startup errors are reported separately. Custom
wrapper scripts are not executed or guessed; use an explicit HAProxy command.
The managed host needs Python 3 and permission to inspect startup settings.
Add forms, text editing, saved versions and Change Center retain the selected
file path. Validation uses the detected sources in their original order before
replacing a file. Only non-hidden .cfg files directly inside each source
directory participate; subdirectories need their own startup argument. Sources
must remain inside haproxy_dir (the configured main file is also allowed).
Docker paths are mapped through existing mounts; saving requires a writable
directory mount because a single-file mount cannot follow atomic replacements.
Configuration links for HAProxy, NGINX, Apache and Keepalived use the same
lossless _p_ path tokens. The previous slash-to-92 URL format is no longer
accepted. Open files from the configuration list to obtain new links. Browser
history and drafts keyed by the old format are not migrated.
The web launcher uses roxy_wi_gunicorn by default. To select a custom config,
set GUNICORN_CMD_ARGS="--config /path/to/gunicorn.conf.py". Keep the database
readiness monitor lifecycle by importing its hooks in that config:
from roxy_wi_gunicorn import post_worker_init, worker_exitIf you define your own versions of these hooks, call the corresponding Roxy-WI hook from each one. Application imports belong inside worker hooks, after fork.
| Start here | Operate and integrate |
|---|---|
| Documentation index | Operations and troubleshooting |
| Change Center guide | Configuration and settings |
| Plans and feature availability | Configuration backups |
| Deployment guide | Let's Encrypt |
Manage blacklists and whitelists in Add → Lists. Select a server to view the group catalog, inspect active ACLs, compare files on linked nodes, and edit IPv4, IPv6 or CIDR entries. Save and apply replaces loaded ACLs through Runtime API transactions (HAProxy 2.4+) and persists the files on each target. New, unused lists are saved as files; attach them to a configuration section and reload HAProxy before they can affect traffic. Files also used as maps are managed separately through Maps.
The editor checks revisions before writing and reports file/runtime results for each node. A lost response is reported as unknown; use Reload state and review differences before retrying. There is no atomic transaction across nodes. Deleting a list is blocked while a configuration or active ACL still uses it. The old list endpoints remain compatible adapters; explicit legacy reload or restart requests retain their service action. Docker/Podman list files require a persistent directory mount, not a bind mount of an individual file.
- Report a bug or discuss an idea.
- Contribute code, documentation or a reproducible example.
- Find support, compare plans, or follow the Telegram channel.
- Report vulnerabilities through the private reporting instructions.
Roxy-WI is licensed under Apache 2.0. Paid subscriptions provide the features and support described on the plans page.