Simplify Nginx Management with nginxWebUI: Install, Docker & Usage Guide

Function Overview

nginxWebUI is a graphical tool for managing Nginx configurations via a web interface. It supports HTTP and TCP forwarding, reverse proxy, load balancing, static HTML serving, automatic SSL certificate issuance and renewal, and can generate a complete nginx.conf file for deployment.

The tool can manage multiple Nginx servers, allowing one‑click switching and synchronization of configurations across a cluster. While it does not cover every Nginx feature, it handles about 90% of daily use cases, and custom parameters can be added through template files.

Technical Details

The project is built on the Solon web framework and uses an embedded H2 database, eliminating the need for an external database on the server.

SSL certificates are obtained via Let’s Encrypt using the acme.sh script, with automatic renewal at 2 am daily for certificates older than 60 days (Linux only).

When TCP/IP forwarding is enabled, the system automatically loads the ngx_stream_module.so module if the underlying Nginx includes the stream module; otherwise, recompilation with --with-stream is required.

Jar Installation Instructions

Example for Ubuntu:

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

Example for CentOS:

yum install java-11-openjdk
yum install nginx

Example for 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 directory and add <code>%JAVA_HOME%\bin</code> to PATH, then restart the computer.

Download the latest JAR package:

Linux: mkdir /home/nginxWebUI/
       wget -O /home/nginxWebUI/nginxWebUI.jar http://file.nginxwebui.cn/nginxWebUI-3.4.4.jar
Windows: download http://file.nginxwebui.cn/nginxWebUI-3.4.4.jar to D:/home/nginxWebUI/nginxWebUI.jar

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/

Optional parameters (all non‑mandatory) include --server.port, --project.home, --spring.database.type=mysql, --spring.datasource.url=jdbc:mysql://ip:port/nginxwebui, --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 both Nginx and nginxWebUI.

Install Docker:

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

Pull and run the image:

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

Key notes:

Use --net=host to map all host ports.

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

Pass Java options via -e BOOT_OPTIONS to change the listening port.

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

Docker‑compose example:

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

Compilation and Service Setup

Build the project with Maven: mvn clean package Build a Docker image: docker build -t nginxwebui:latest . Create a systemd service file /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

Access the UI at http://<em>host</em>:8080. The first login prompts for an administrator account. Administrators can add or modify other admin accounts, configure HTTP, TCP, reverse proxy, SSL certificates (including uploading PEM files), load balancing, static HTML files, and view generated nginx.conf files. The tool also supports remote server management and one‑click synchronization across multiple Nginx instances.

API and Documentation

Open the Swagger‑like documentation at http://<em>host</em>:8080/doc.html. API calls require a token obtained by enabling the user’s API permission in the admin panel and authenticating with username and password.

Password Recovery

To recover a lost password, stop the application ( pkill java) and restart the JAR with the --project.findPass=true flag, which prints all usernames and passwords and disables two‑factor authentication.

Open Source

Source code is available at https://github.com/cym1102/nginxWebUI .