Getting Started

Try It Now

You can try Nginx UI directly by the demo.

• Username：admin
• Password：admin

Before Use

The Nginx UI follows the Debian web server configuration file standard. Created site configuration files will be placed in the sites-available folder that under the Nginx configuration folder (auto-detected). The configuration files for an enabled site will create a soft link to the sites-enabled folder. You may need to adjust the way the configuration files are organised.

For non-Debian (and Ubuntu) systems, you may need to change the contents of the nginx.conf configuration file to the Debian style as shown below.

http {
	# ...
	include /etc/nginx/conf.d/*.conf;
	include /etc/nginx/sites-enabled/*;
}

For more information: debian/conf/nginx.conf

Installation

We provide several installation methods to suit different needs:

• macOS/Linux: Use Homebrew for the easiest installation
• Windows: Use Winget for Windows package management
• Linux: Use the installation script to directly control the host machine's Nginx
• Docker: Install via Docker with our bundled image that includes Nginx
• Advanced: Download from latest release and run executable directly, or manually build it

In the first runtime of Nginx UI, please visit http://<your_server_ip>:<listen_port> in your browser to complete the follow-up configurations.

In addition, we provide an example of using Nginx to reverse proxy Nginx UI, which can be used after installation is complete.

Getting the Install Secret

Before the web setup can continue, Nginx UI requires a one-time install secret on first startup. The secret is stored in a hidden file named .install_secret in the same directory as app.ini.

You can obtain it in different ways depending on how you installed Nginx UI:

• Linux installation script: The script prints the secret after the service starts. If you miss it, read $DATA_PATH/.install_secret (default: /usr/local/etc/nginx-ui/.install_secret).
• Homebrew: Read .install_secret from the same directory as app.ini, such as /opt/homebrew/etc/nginx-ui/.install_secret, /usr/local/etc/nginx-ui/.install_secret, or /home/linuxbrew/.linuxbrew/etc/nginx-ui/.install_secret.
• Docker / Docker Compose: Read .install_secret from the host directory mounted to /etc/nginx-ui. If you did not mount that directory, run docker exec <container_name> cat /etc/nginx-ui/.install_secret.
• Winget: Read .install_secret from the same directory as app.ini, typically %LOCALAPPDATA%\nginx-ui\.install_secret or C:\ProgramData\nginx-ui\.install_secret.
• Run executable directly / manual build: Read .install_secret from the same directory as the config file you pass to -config.

The secret is only valid during the first-run setup window and will be removed after setup completes or expires.

Install with Homebrew

For macOS and Linux users, you can install Nginx UI using Homebrew, which provides the easiest installation experience.

TIP

This installation method is available for macOS and Linux. For other operating systems, please use alternative installation methods.

Install

brew install 0xjacky/tools/nginx-ui

Start Service

# Start the service
brew services start nginx-ui

# Or run in foreground
nginx-ui

Stop Service

brew services stop nginx-ui

Upgrade

brew upgrade nginx-ui

Uninstall

# Stop the service first
brew services stop nginx-ui

# Uninstall the package
brew uninstall nginx-ui

# Optionally remove the tap
brew untap 0xjacky/tools

WARNING

After uninstalling, configuration files and data will be preserved in:

• macOS: ~/Library/Application Support/nginx-ui/
• Linux: ~/.local/share/nginx-ui/ or ~/.config/nginx-ui/

If you want to completely remove all data, please delete these directories manually.

Install with Docker

Our docker image uozi/nginx-ui:latest is based on the latest nginx image and can be used to replace the Nginx on the host. By publishing the container's port 80 and 443 to the host, you can easily make the switch.

TIP

The official Docker image listens on container ports 80 and 443. Requests to container port 80 are reverse proxied to the Nginx UI backend at 127.0.0.1:9000. Access Nginx UI through the host port that you publish to container port 80. When using this container for the first time, ensure that the volume mapped to /etc/nginx is empty. If you want to host static files, you can map directories to container.

WARNING

If you want to manage the Nginx of the host, please choose another installation method. We recommend using the installation script if you are using Linux.

Docker Deploy Example

docker run -dit \
  --name=nginx-ui \
  --restart=always \
  -e TZ=Asia/Shanghai \
  -v /mnt/user/appdata/nginx:/etc/nginx \
  -v /mnt/user/appdata/nginx-ui:/etc/nginx-ui \
  -v /var/www:/var/www \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 8080:80 -p 8443:443 \
  uozi/nginx-ui:latest

In this example, port 80 and 443 of the container are mapped to port 8080 and 8443 of the host respectively. You need to visit http://<your_server_ip>:8080 to access Nginx UI.

Run Executable Directly

It is not recommended to run the Nginx UI executable directly for non-testing purposes. We recommend configuring it as a daemon or using the installation script on Linux.

Config

echo '[server]\nPort = 9000' > app.ini

TIP

The server can still be started without app.ini, it will listen on the default port 9000.

Run

In Terminal

nginx-ui -config app.ini

In Background

nohup ./nginx-ui -config app.ini &

Stop

In Terminal

^C   # Press Ctrl+C

In Background

kill -9 $(ps -aux | grep nginx-ui | grep -v grep | awk '{print $2}')