nginxWebUI: Graphical Management Tool for Nginx – Features, Installation, Docker, and Usage Guide

Feature Overview

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

The tool can manage multiple Nginx servers, switch between them with one click, and synchronize configurations across the cluster. While it does not cover every Nginx feature, it supports roughly 90% of daily use cases, and 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 via Let's Encrypt using the acme.sh script, with daily renewal at 02:00 for certificates older than 60 days (Linux only).

When enabling TCP/IP forwarding, low‑version Nginx may need to be compiled with the --with-stream option; the official Ubuntu 18.04 package already includes the stream module, and the system will automatically load ngx_stream_module.so if needed.

Jar Installation Instructions

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 directory and add
%JAVA_HOME%\bin
to PATH
Restart the computer

Download the latest nginxWebUI.jar package, place it under /home/nginxWebUI/ (Linux) or D:/home/nginxWebUI/ (Windows), and start it with optional parameters such as --server.port and --project.home .

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

Important notes:

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

Map the volume /home/nginxWebUI:/home/nginxWebUI to persist configuration, logs, and certificates.

The BOOT_OPTIONS environment variable can pass Java options such as --server.port .

Log files 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"

Building from Source

Compile with Maven:

mvn clean package

Build a Docker image:

docker build -t nginxwebui:latest .

Systemd Service for Auto‑Start

Create /etc/systemd/system/nginxwebui.service with the following content:

[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:// your‑host :8080 in a browser. The first login prompts for an admin account. After logging in you can manage:

HTTP parameters – configure virtual hosts, enable logging, and set up redirects.

TCP/stream parameters – optional stream configuration.

Reverse proxy – set up upstream servers, enable SSL (upload PEM/key or use auto‑issued certs), and enable HTTP/2.

Load balancing – define upstream groups and select them in proxy settings.

Static HTML – upload compressed HTML packages for quick static site hosting.

Certificate management – add, issue, and auto‑renew certificates via acme.sh (requires Aliyun DNS credentials).

Backup & restore – view and roll back previous nginx.conf versions.

Remote server management – add other Nginx servers (IP, username, password) to control them from a single UI, and sync configurations across servers.

API Development

Access the Smart‑Doc API page at http:// your‑host :8080/doc.html . API calls require a token supplied in the HTTP header; the token is obtained by enabling the user’s API permission in the admin panel and then calling the token endpoint with the username and password.

Password Recovery

To recover a lost password or disable two‑step verification:

Stop nginxWebUI: pkill java

Run the jar with recovery parameters: java -jar nginxWebUI.jar --project.home=/home/nginxWebUI/ --project.findPass=true The --project.findPass flag prints all usernames and passwords.

Open‑Source Repository

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