Skip to content

Install with Homebrew

This installation method is designed for macOS and Linux users who have already installed Homebrew.

Prerequisites

  • macOS: macOS 11 Big Sur or later (amd64 / arm64)
  • Linux: Most modern Linux distributions (Ubuntu, Debian, CentOS, etc.)
  • Homebrew installed on your system

If you don't have Homebrew installed, you can install it with:

bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Installation

Install Nginx UI

bash
brew install 0xjacky/tools/nginx-ui

This command will:

  • Add the 0xjacky/tools tap to your Homebrew
  • Download and install the latest stable version of Nginx UI
  • Set up the necessary dependencies
  • Create default configuration files and directories

Verify Installation

After installation, you can verify that Nginx UI is installed correctly:

bash
nginx-ui --version

Service Management

Nginx UI can be managed as a system service using Homebrew's service management features.

Start Service

bash
# Start the service and enable it to start at boot
brew services start nginx-ui

# Or start the service for the current session only
brew services run nginx-ui

Stop Service

bash
brew services stop nginx-ui

Restart Service

bash
brew services restart nginx-ui

Check Service Status

bash
brew services list | grep nginx-ui

Running Manually

If you prefer to run Nginx UI manually instead of as a service:

bash
# Run in foreground
nginx-ui

# Run with custom config
nginx-ui serve -config /path/to/your/app.ini

# Run in background
nohup nginx-ui serve &

Configuration

The configuration file is automatically created during installation and located at:

  • macOS (Apple Silicon): /opt/homebrew/etc/nginx-ui/app.ini
  • macOS (Intel): /usr/local/etc/nginx-ui/app.ini
  • Linux: /home/linuxbrew/.linuxbrew/etc/nginx-ui/app.ini

Data is stored in:

  • macOS (Apple Silicon): /opt/homebrew/var/nginx-ui/
  • macOS (Intel): /usr/local/var/nginx-ui/
  • Linux: /home/linuxbrew/.linuxbrew/var/nginx-ui/

The default configuration includes:

ini
[app]
PageSize = 10

[server]
Host = 0.0.0.0
Port = 9000
RunMode = release

[cert]
HTTPChallengePort = 9180

[terminal]
StartCmd = login

Updating

Update Nginx UI

bash
brew upgrade nginx-ui

Update Homebrew and all packages

bash
brew update && brew upgrade

Uninstallation

Stop and Uninstall

bash
# Stop the service first
brew services stop nginx-ui

# Uninstall the package
brew uninstall nginx-ui

Remove the Tap (Optional)

If you no longer need the tap:

bash
brew untap 0xjacky/tools

Remove Configuration and Data

WARNING

This will permanently delete all your configurations, sites, certificates, and data. Make sure to backup any important data before proceeding.

bash
# macOS (Apple Silicon)
sudo rm -rf /opt/homebrew/etc/nginx-ui/
sudo rm -rf /opt/homebrew/var/nginx-ui/

# macOS (Intel)
sudo rm -rf /usr/local/etc/nginx-ui/
sudo rm -rf /usr/local/var/nginx-ui/

# Linux
sudo rm -rf /home/linuxbrew/.linuxbrew/etc/nginx-ui/
sudo rm -rf /home/linuxbrew/.linuxbrew/var/nginx-ui/

Troubleshooting

Port Conflicts

If you encounter port conflicts (default port is 9000), you need to modify the configuration file:

  1. Edit the configuration file:

    bash
    # macOS (Apple Silicon)
    sudo nano /opt/homebrew/etc/nginx-ui/app.ini
    
    # macOS (Intel)
    sudo nano /usr/local/etc/nginx-ui/app.ini
    
    # Linux
    sudo nano /home/linuxbrew/.linuxbrew/etc/nginx-ui/app.ini
  2. Change the port in the [server] section:

    ini
    [server]
    Host = 0.0.0.0
    Port = 9001
    RunMode = release
  3. Restart the service:

    bash
    brew services restart nginx-ui

Viewing Service Logs

To troubleshoot service issues, you can view the logs using these commands:

Homebrew Service Logs

Nginx UI's Homebrew formula includes proper log configuration:

bash
# View service status and log file paths
brew services info nginx-ui

# View standard output logs
tail -f $(brew --prefix)/var/log/nginx-ui.log

# View error logs
tail -f $(brew --prefix)/var/log/nginx-ui.err.log

# View both logs simultaneously
tail -f $(brew --prefix)/var/log/nginx-ui.log $(brew --prefix)/var/log/nginx-ui.err.log

systemd Logs (Linux)

For Linux systems using systemd:

bash
# View service logs
journalctl -u homebrew.mxcl.nginx-ui -f

# View recent logs
journalctl -u homebrew.mxcl.nginx-ui --since "1 hour ago"

Manual Debugging

If you need to debug service issues, you can run manually to see output:

bash
# Run in foreground to see all output
nginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini

# Check if the service is running
ps aux | grep nginx-ui

Permission Issues

If you encounter permission issues when managing Nginx configurations:

  1. Make sure your user has the necessary permissions to read/write Nginx configuration files
  2. You might need to run Nginx UI with elevated privileges for certain operations
  3. Check file permissions:
    bash
    # Check configuration file permissions
    ls -la $(brew --prefix)/etc/nginx-ui/app.ini
    
    # Check data directory permissions
    ls -la $(brew --prefix)/var/nginx-ui/

Service Won't Start

If the service fails to start:

  1. Check the service status:

    bash
    brew services list | grep nginx-ui
  2. Verify the configuration file exists and is valid:

    bash
    # Check if config file exists
    ls -la $(brew --prefix)/etc/nginx-ui/app.ini
    
    # Test configuration
    nginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini --help
  3. Try running manually to see error messages:

    bash
    nginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini
  4. Check for port conflicts:

    bash
    # Check if port 9000 is already in use
    lsof -i :9000
    
    # Check if HTTP challenge port is in use
    lsof -i :9180

Getting Help

If you encounter any issues:

  1. Check the official documentation
  2. Search for existing issues on GitHub
  3. Create a new issue if your problem isn't already reported

Next Steps

After installation, you can:

  1. Access the web interface at http://localhost:9000
  2. Complete the initial setup wizard
  3. Start configuring your Nginx sites
  4. Explore the configuration guides for advanced setups

Released under the AGPL-3.0 License. (d6ecf1d5)