Deploy and Manage Nginx with the Open‑Source nginxWebUI Tool

Feature Overview

nginxWebUI is a graphical web UI for managing Nginx configurations. It supports HTTP and TCP forwarding, reverse proxy, load balancing, static HTML serving, and automatic SSL certificate issuance and renewal via Let’s Encrypt. The UI can generate a complete nginx.conf file and control Nginx start/reload operations.

The tool can manage multiple Nginx servers, allowing one‑click switching and configuration synchronization across a cluster. Uncovered Nginx directives can be added through custom parameter templates.

Technical Details

Built on the Solon web framework with an embedded H2 database, so no external database installation is required. SSL certificates are obtained with the acme.sh script; renewal runs daily at 02:00 and only renews certificates older than 60 days. The application runs on Linux.

For Nginx versions that lack the stream module, the module ngx_stream_module.so is loaded when Nginx is compiled with --with-stream. Ubuntu 18.04 packages already include this module.

JAR Installation

Install Java runtime and Nginx

apt update
apt install openjdk-11-jdk nginx

yum install java-11-openjdk nginx

On Windows, download the JDK from https://www.oracle.com/java/technologies/downloads/ and Nginx from http://nginx.org/en/download.html. Set JAVA_HOME to the JDK directory and add its bin to PATH , then reboot.

Download the JAR package

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

# Windows
Download to D:/home/nginxWebUI/nginxWebUI.jar

Start the program

# Linux (run as root)
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/

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

--spring.datasource.username=root

--spring.datasource.password=pass

Run the program as root and change default passwords to strong values.

Docker Installation

Install Docker

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

Pull the image docker pull cym1102/nginxwebui:latest Run the container

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

Key notes:

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

Mount /home/nginxWebUI:/home/nginxWebUI to persist data, logs, and certificates.

The environment variable BOOT_OPTIONS can override Java start options (e.g., change the port).

Log file is located at /home/nginxWebUI/log/nginxWebUI.log.

Docker‑compose example:

version: "3.2"
services:
  nginxWebUi-server:
    image: cym1102/nginxwebui:latest
    volumes:
      - /home/nginxWebUI:/home/nginxWebUI
    environment:
      BOOT_OPTIONS: "--server.port=8080"
    privileged: true
    network_mode: "host"

Systemd Service Installation

Create service file

# /etc/systemd/system/nginxwebui.service
[Unit]
Description=NginxWebUI
After=syslog.target 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

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

Usage

Open http://<em>host</em>:8080 in a browser. The first login prompts for admin account initialization. After logging in, administrators can add or modify other admin accounts.

API Development

The system provides HTTP APIs documented at http://<em>host</em>:8080/doc.html. API calls require a token passed in the request header. Tokens are generated by enabling token generation for a user in the admin panel.

Password Recovery

Stop nginxWebUI pkill java Run with password‑recovery flags

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

Parameters: --project.home: directory of the project files --project.findPass: when true, prints all usernames and passwords and disables two‑factor authentication

Open‑Source Repository

Source code is available at:

https://github.com/cym1102/nginxWebUI