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:
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
Change the port in the
[server]
section:ini[server] Host = 0.0.0.0 Port = 9001 RunMode = release
Restart the service:
bashbrew 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:
- Make sure your user has the necessary permissions to read/write Nginx configuration files
- You might need to run Nginx UI with elevated privileges for certain operations
- 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:
Check the service status:
bashbrew services list | grep nginx-ui
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
Try running manually to see error messages:
bashnginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini
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:
- Check the official documentation
- Search for existing issues on GitHub
- Create a new issue if your problem isn't already reported
Next Steps
After installation, you can:
- Access the web interface at
http://localhost:9000
- Complete the initial setup wizard
- Start configuring your Nginx sites
- Explore the configuration guides for advanced setups