nginxWebUI: Graphical Management Tool for Nginx Configuration and Deployment

Function Description

nginxWebUI is a graphical management tool for Nginx configuration that allows users to quickly configure Nginx functions via a web interface, including HTTP forwarding, TCP forwarding, reverse proxy, load balancing, static HTML serving, automatic SSL certificate issuance, renewal, and configuration. After configuration, it can generate an nginx.conf file and control Nginx to start or reload using that file, completing a closed‑loop graphical control of Nginx.

The tool can also manage multiple Nginx server clusters, allowing one‑click switching to a specific server for configuration, and one‑click synchronization of a server’s configuration to others, facilitating cluster management.

Although nginxWebUI does not cover every Nginx feature, it supports roughly 90% of daily usage scenarios. Uncovered configuration items can be added via custom parameter templates that generate unique configuration entries in the conf file.

After deploying this project, users no longer need to search the internet for configuration snippets or manually obtain and configure SSL certificates; all operations can be performed through the web UI.

Demo address: http://test.nginxwebui.cn:8080
Username: admin
Password: admin

Technical Description

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

It obtains SSL certificates via Let’s Encrypt using the acme.sh script for automated issuance and renewal. Renewal runs daily at 02:00 AM, and only certificates older than 50 days are renewed. This feature works only on Linux.

When TCP/IP forwarding is enabled, some older Nginx versions may need to be recompiled with the --with-stream option to include the stream module. However, on Ubuntu 18.04 the official repository already provides Nginx with the stream module, so recompilation is unnecessary. If a TCP forwarding item is configured, the system automatically adds the ngx_stream_module.so configuration; otherwise it is omitted to keep the generated nginx.conf minimal.

JAR Installation Instructions

Note: The project must be run as the root user, which poses security risks; be sure to change the default password to a strong one.

1. Install Java runtime and Nginx

Ubuntu:

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

CentOS:

yum install java-11-openjdk
yum install nginx

Windows:

Download JDK from https://www.oracle.com/java/technologies/downloads/
Download Nginx from http://nginx.org/en/download.html
Set JAVA_HOME to the JDK installation directory
Add %JAVA_HOME%\bin to the Path environment variable
Reboot the computer

2. Download the latest JAR package

Linux: wget -O /home/nginxWebUI/nginxWebUI.jar http://file.nginxwebui.cn/nginxWebUI-3.1.8.jar
Windows: Use a browser to download http://file.nginxwebui.cn/nginxWebUI-3.1.8.jar

3. Start the program

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

Parameter description (all optional):

--server.port Port to bind; defaults to 8080.

--project.home Directory for project configuration files, database files, certificates, logs, etc.; defaults to /home/nginxWebUI/.

--spring.database.type=mysql Use MySQL instead of the embedded H2 database.

--spring.datasource.url=jdbc:mysql://ip:port/nginxwebui Database URL.

--spring.datasource.username=root Database username.

--spring.datasource.password=pass Database password.

Note: Append an ampersand (&) to Linux commands to run the program in the background.

Docker Installation Instructions

The project provides Docker images for x86/x86_64/arm64/arm v7 platforms, bundling both Nginx and nginxWebUI for an all‑in‑one management and runtime solution.

1. Install Docker

Ubuntu:

apt install docker.io

CentOS:

yum install docker

2. Pull the image

docker pull cym1102/nginxwebui:latest

3. Run the container

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

Important notes:

Use --net=host to map all host ports because the internal Nginx may bind to any port.

Map the host path /home/nginxWebUI to the container to persist data such as databases, Nginx configuration files, logs, and certificates; this ensures data is retained when upgrading the image.

The -e BOOT_OPTIONS environment variable can pass Java startup options, e.g., to change the listening port (default 8080).

Logs are stored by default at /home/nginxWebUI/log/nginxWebUI.log .

Update Notes

1. Windows now supports automatic updates.

2. Implemented a Java‑based tail command for log tracking, removing the need for WebSocket.

3. Fixed white‑screen issue when proxying through non‑443/80 ports.

4. Fixed file import failure for oversized files.

5. Fixed remote synchronization failure for large data sets.

6. Fixed incorrect log path after specifying project.home .

7. Fixed garbled output when running Docker on Windows.

8. Updated MySQL driver to 8.x to mitigate vulnerabilities.