Open‑Source Nginx Visual Configurator: A Hands‑On Guide

Function Overview

nginxWebUI provides a graphical web interface for managing Nginx configurations, including HTTP forwarding, TCP forwarding, reverse proxy, load balancing, static HTML serving, automatic SSL certificate issuance and renewal via Let’s Encrypt, and one‑click generation of nginx.conf. The UI can start and reload Nginx, forming a closed‑loop management process.

It can manage multiple Nginx servers in a cluster, allowing one‑click switching between servers and synchronizing configurations and certificates across them. The tool covers roughly 90 % of daily Nginx configuration needs; uncovered options can be added through custom parameter templates.

Technical Details

The project is built on the Solon web framework and uses an embedded H2 database, so no external database installation is required.

SSL certificates are obtained automatically with the acme.sh script. Renewal runs daily at 02:00 AM and only renews certificates older than 60 days; this works on Linux systems.

For TCP/IP forwarding, low‑version Nginx may need recompilation with the --with-stream flag to enable the ngx_stream_module.so module. On Ubuntu 18.04 the official package already includes the stream module, so recompilation is unnecessary.

Jar Installation (Linux Example)

Install Java runtime and Nginx:

apt update
apt install openjdk-11-jdk
apt install nginx

Download the latest jar package:

mkdir /home/nginxWebUI/
wget -O /home/nginxWebUI/nginxWebUI.jar http://file.nginxwebui.cn/nginxWebUI-3.4.4.jar

Start the program:

nohup java -jar -Dfile.encoding=UTF-8 /home/nginxWebUI/nginxWebUI.jar --server.port=8080 --project.home=/home/nginxWebUI/ > /dev/null &

Optional command‑line parameters (all non‑mandatory): --server.port: port to bind (default 8080) --project.home: directory for configuration files, databases, certificates, logs (default /home/nginxWebUI/) --spring.database.type=mysql: use MySQL instead of the embedded H2 --spring.datasource.url=jdbc:mysql://ip:port/nginxwebui: MySQL JDBC URL --spring.datasource.username=root and

--spring.datasource.password=pass

Docker Installation

The project provides Docker images for x86_64, arm64, and arm v7 platforms, bundling Nginx and nginxWebUI together.

Install Docker:

apt install docker.io   # Ubuntu
yum install docker      # CentOS

Pull the image: docker pull cym1102/nginxwebui:latest Run the container (host network mode is required to expose all possible Nginx ports):

docker run -itd \
  -v /home/nginxWebUI:/home/nginxWebUI \
  -e BOOT_OPTIONS="--server.port=8080" \
  --privileged=true \
  --net=host \
  cym1102/nginxwebui:latest

Use --net=host to map host ports because Nginx may listen on any port.

Mount /home/nginxWebUI to persist configuration, logs, and certificates across image upgrades.

The -e BOOT_OPTIONS variable can pass Java start‑up options, e.g., --server.port.

Systemd Service (Linux)

Create a service file at /etc/systemd/system/nginxwebui.service:

[Unit]
Description=NginxWebUI
After=syslog.target
After=network.target

[Service]
Type=simple
User=root
Group=root
WorkingDirectory=/home/nginxWebUI
ExecStart=/usr/bin/java -jar /home/nginxWebUI/nginxWebUI.jar
Restart=always

[Install]
WantedBy=multi-user.target

Enable and start the service:

systemctl daemon-reload
systemctl enable nginxwebui.service
systemctl start nginxwebui.service

Usage

Open http://<em>host_ip</em>:8080 in a browser. The first login prompts creation of an administrator account.

After logging in, the UI allows:

Managing administrators.

Configuring HTTP forwarding, enabling logging, and adding custom HTTP parameters.

Configuring TCP stream parameters (optional).

Setting up reverse proxy with SSL: upload PEM/key files or use Let’s Encrypt, enable HTTP/2, and configure HTTP to HTTPS redirection.

Defining load‑balancing upstreams and selecting them in reverse‑proxy rules.

Uploading static HTML packages to a designated path for direct serving.

Managing certificates with automatic renewal.

Viewing versioned nginx.cnf backups and rolling back to previous configurations.

Adding remote Nginx hosts (IP, username, password) and synchronizing configurations and certificates with one click.

API

The system exposes HTTP APIs documented at http://<em>host_ip</em>:8080/doc.html. Calls require a token passed in the request header. The token is obtained by enabling API permissions for a user, then authenticating with the username and password to retrieve the token.

Password Recovery

Stop nginxWebUI: pkill java Run the jar with password‑recovery parameters:

java -jar nginxWebUI.jar --project.home=/home/nginxWebUI/ --project.findPass=true

Successful execution prints all usernames and passwords and disables two‑step verification.

Source Code

Open‑source repository: https://github.com/cym1102/nginxWebUI