nginx-ui/docs/guide/install-homebrew.md

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:

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

Installation

Install Nginx UI

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:

nginx-ui --version

Service Management

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

Start Service

# 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

brew services stop nginx-ui

Restart Service

brew services restart nginx-ui

Check Service Status

brew services list | grep nginx-ui

Running Manually

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

# 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:

[app]
PageSize = 10

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

[cert]
HTTPChallengePort = 9180

[terminal]
StartCmd = login

Updating

Update Nginx UI

brew upgrade nginx-ui

Update Homebrew and all packages

brew update && brew upgrade

Uninstallation

Stop and Uninstall

# 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:

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.

:::

# 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:

   # 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:

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

3. Restart the service:

   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:

# 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:

# 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:

# 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:

   # 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:

   brew services list | grep nginx-ui
   

2. Verify the configuration file exists and is valid:

   # 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:

   nginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini
   

4. Check for port conflicts:

   # 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