nginxWebUI: a web panel that writes nginx.conf for you

What nginxWebUI replaces, and for whom

The problem it targets is configuration literacy. nginx directives are terse, error messages point at line numbers rather than intent, and a single misplaced semicolon takes a site down. nginxWebUI turns that into forms: HTTP parameters, stream parameters, reverse proxy entries, upstream blocks, static HTML uploads, password files and IP allow or deny lists. The README states the project covers roughly 90 percent of everyday nginx configuration and that anything outside that can be written as a custom parameter template injected into the generated conf file. That last clause matters more than the percentage. It is the escape hatch that keeps the tool from becoming a cage.

The audience is narrow and specific. It is an operator running nginx on one machine, or a handful, who wants certificate renewal handled and who is tired of looking up proxy_pass syntax. The README also names cluster management, but the feature comparison table splits that: node and group management, node configuration sync, node data collection and node status statistics are pro edition only. So the open source edition is a single-host tool with a multi-host story that stops at switching between servers and syncing one machine's configuration to others by hand.

Solon, SQLite, and a generated nginx.conf

The stack is deliberately small. The README describes a Solon-based web system with SQLite as the database, so no database server has to be installed. Everything the panel knows lives in a project home directory: the database file, certificate files, logs, and the nginx configuration it produces. The Dockerfile confirms the shape of the runtime, building on alpine:3.24 and installing openjdk8-jre, nginx, and a long list of nginx modules including nginx-mod-stream, nginx-mod-http-lua, nginx-mod-http-brotli and nginx-mod-rtmp, then copying the built jar to /home/nginxWebUI.jar and running tini entrypoint.sh.

The data flow is one-directional and explicit. You fill in forms, the application writes nginx.conf, and it then controls nginx to start or reload with that file. The README calls this a graphical control loop. Two details show the generator is not naive. First, if a TCP forwarding entry exists, the system automatically adds the ngx_stream_module.so configuration line, and if it does not, the line is omitted, which the README frames as keeping the config file as lean as possible. Second, certificate issuance uses Let's Encrypt through the acme.sh script in DNS mode, and renewal runs daily at 2 a.m., but only for certificates older than 60 days. Certificates you do not enable for renewal are simply left alone.

Installing nginxWebUI from the jar

The jar route is the one the README documents first. Install a JDK and nginx, then download the release jar. The README's Ubuntu commands are these:

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

Next, fetch the current release. The README pins the example to version 4.4.2 and notes that for a newer version you only change the version in the path:

mkdir /home/nginxWebUI/
wget -O /home/nginxWebUI/nginxWebUI.jar https://gitee.com/cym1102/nginxWebUI/releases/download/4.4.2/nginxWebUI-4.4.2.jar

Start it with the two documented flags. The README warns that the trailing ampersand is what puts the process in the background:

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

Both flags are optional. --server.port defaults to 8080 and --project.home defaults to /home/nginxWebUI/. The README also documents --spring.database.type=mysql or postgresql with --spring.datasource.url, --spring.datasource.username and --spring.datasource.password if you would rather not use SQLite, plus --init.admin, --init.pass and --init.api=true for the first account. Open http://<server>:8080 and the first visit asks you to initialise the administrator account.

The Docker route and why it insists on host networking

The image bundles nginx and nginxWebUI together, and the README states it supports x86_64, arm64 and arm v7. Pull it, then run it with two non-negotiable settings:

docker pull cym1102/nginxwebui:latest

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

The README gives the reasoning for --net=host directly: the internal nginx may listen on any port, so every host port must be mapped, which host networking does and a port-mapping list cannot. The volume is equally load-bearing. /home/nginxWebUI holds the database, nginx configuration files, logs and certificates, so keeping it outside the container is what lets you upgrade the image without losing data. Logs land in /home/nginxWebUI/log/nginxWebUI.log by default. A docker-compose equivalent is documented with network_mode: "host" and the same BOOT_OPTIONS environment variable.

The trade-off is real and worth stating plainly. Host networking means the panel and nginx share the host's network namespace, so nothing is isolated. Anyone who reaches port 8080 reaches the panel. The README's own warning is blunt: the project needs to run system commands as root, is therefore easy for an attacker to abuse, and you must change the password to a complex one.

Where nginxWebUI is the wrong tool

The most concrete limitation is the certificate path. The README states issuance uses acme.sh in DNS mode and requires an Aliyun aliKey and aliSecret to be obtained beforehand, and that certificates can only be issued on Linux. That is a hard dependency on one DNS provider's API credentials, and it rules out Windows hosts for issuance entirely. If you use Cloudflare, Route 53 or a self-hosted DNS API, the documented flow does not describe your case.

TCP forwarding carries a second constraint. The README warns that some older nginx builds may need recompiling with the --with-stream parameter to get the stream module, and notes that under Ubuntu 18.04 the distribution's nginx already includes it. The Docker image sidesteps this because nginx-mod-stream is installed in the image. So on a hand-built nginx, adding a stream entry in the panel can fail at reload time for a reason that has nothing to do with the panel.

Then there is the operational model itself. A tool that runs as root, writes nginx.conf and reloads nginx is a privileged component sitting in front of your web traffic. The README's backup file management section offers a mitigation: you can see the historical versions of nginx.conf and roll back to an earlier one when nginx breaks. That is a genuine safety net, but it is a manual recovery step, not a validation gate. The README does not document a dry-run or a syntax check before reload. If the panel writes a configuration nginx rejects, the practical sequence is that something breaks, you notice, and you restore a backup.

How it differs from Nginx Proxy Manager

Nginx Proxy Manager is the obvious comparison, and the difference is scope rather than quality. Nginx Proxy Manager is built around the proxy host as its central object: you add a host, point it at a backend, attach a certificate, done. nginxWebUI is built around nginx's own configuration structure. Its menus are named after the directives they write, with separate screens for HTTP parameters, stream parameters, reverse proxy (the server block), and upstream (the load balancing block). That means nginxWebUI exposes more of nginx's surface, including custom parameter templates for directives the forms do not cover, and it can manage raw stream forwarding, which a proxy-host-centric tool does not present as a first-class concept.

The cost of that breadth is more decisions. In Nginx Proxy Manager you rarely think about where a setting belongs. In nginxWebUI you choose whether something is an HTTP parameter, a server-level setting or an upstream attribute, and the custom template exists precisely because that mapping is not always obvious. If your requirement is ten proxy hosts with Let's Encrypt certificates, the simpler model is easier to reason about. If you need stream blocks, upstream tuning and a place to paste directives the UI does not model, nginxWebUI's structure is the point.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-07-05. Release 4.4.2 landed the same day, 4.4.1 the day before, and 4.4.0 on 2026-06-02, so the release cadence over that window was frequent. The project is published under a licence that GitHub reports as NOASSERTION, which means the repository's LICENSE file does not match a standard identifier the platform recognises. Read that file yourself before you build anything commercial on top of it; I am not going to guess at its terms.

The licence question is entangled with the edition question, and this is the part most likely to surprise an adopter. The README ships a feature comparison table with a pro edition hosted at pro.nginxwebui.cn. Basic parameters, HTTP parameters, reverse proxy, stream parameters, load balancing, parameter templates, static page upload, password file management, IP allow and deny lists, certificate issuance, the API documentation and remote management are all listed as available in both editions. Node and group management, node configuration sync, node data collection, node status statistics, cache configuration, and nginx log collection, viewing, statistics and traffic statistics are marked pro only. If your reason for choosing this project was the cluster management mentioned in its own description, check the table before you commit, because the open source edition does not include the parts that make multi-node operation convenient.

Upgrade cost is low on the jar path: the README says a new version means changing the version in the download path, and the project home directory carries your data across. On Docker, the image is replaced and the /home/nginxWebUI volume persists. The README's backup file management screen, which keeps historical nginx.conf versions, is the rollback mechanism when an upgrade or a configuration change goes wrong.

Editorial conclusion

Adopt nginxWebUI if you run one or a few nginx hosts and want reverse proxy, upstream and certificate work done from a browser instead of a terminal, and you accept that the panel runs as root and must be given a strong password. Do not adopt it if you need node grouping, configuration sync across machines, log collection or traffic statistics: the README's comparison table lists those as pro edition only. Before installing, verify which nginx build you have, because TCP forwarding needs the stream module and the README warns that older nginx may require recompiling with --with-stream. Then check that port 8080 is reachable and that a certificate can actually be issued, since the README states issuance only works on Linux and the acme.sh DNS mode needs an Aliyun aliKey and aliSecret.

Frequently asked questions

Official sources

1. cym1102/nginxWebUI on GitHub
2. Issues
3. README
4. Releases