Skip to content

MACOS-INSTALLATION.md

Latest commit

 

History

History
192 lines (130 loc) · 5.72 KB

MACOS-INSTALLATION.md

File metadata and controls

192 lines (130 loc) · 5.72 KB
Raw

macOS Native Installation

Install Network Optimizer natively on macOS for maximum performance. Native installation is recommended over Docker Desktop, which limits network throughput to ~1.8 Gbps.

Quick Start

git clone https://github.com/Ozark-Connect/NetworkOptimizer.git
cd NetworkOptimizer
./scripts/install-macos-native.sh

The script will:

  1. Install prerequisites via Homebrew (iperf3, nginx, .NET SDK)
  2. Build the application from source
  3. Sign binaries for macOS
  4. Set up OpenSpeedTest with nginx for browser-based speed testing
  5. Create a launchd service for auto-start

Configuration

After installation, edit ~/network-optimizer/start.sh to configure environment variables:

# Timezone
export TZ="America/Chicago"

# Optional: Set admin password (auto-generated on first run if not set)
# export APP_PASSWORD="your-secure-password"

Additional environment variables can be added to start.sh - see docker/.env.example for all available options including:

  • HOST_NAME - Hostname for canonical URL enforcement
  • REVERSE_PROXIED_HOST_NAME - Hostname when behind a reverse proxy (enables HTTPS)
  • OPENSPEEDTEST_HTTPS - Enable HTTPS for speed tests (required for geolocation)
  • Logging__LogLevel__NetworkOptimizer / Logging__LogLevel__Default - Logging verbosity (see Enable Debug Logging)

Note: The app auto-detects its IP address, so HOST_IP is not required for native installations.

After editing, restart the service:

launchctl unload ~/Library/LaunchAgents/net.ozarkconnect.networkoptimizer.plist
launchctl load ~/Library/LaunchAgents/net.ozarkconnect.networkoptimizer.plist

Access

On first run, check the logs for the built-in admin account's auto-generated password, then sign in as admin:

grep -A5 'AUTO-GENERATED' ~/network-optimizer/logs/stdout.log

Service Management

# Stop
launchctl unload ~/Library/LaunchAgents/net.ozarkconnect.networkoptimizer.plist

# Start
launchctl load ~/Library/LaunchAgents/net.ozarkconnect.networkoptimizer.plist

# View logs
tail -f ~/network-optimizer/logs/stdout.log

Upgrading

To upgrade to a newer version:

cd NetworkOptimizer
git pull
./scripts/install-macos-native.sh

The install script preserves your database, encryption keys, and start.sh configuration by backing them up before reinstalling.

Keeping .NET Updated

The macOS native build uses a self-contained .NET runtime bundled with the app. The version you get depends on the .NET SDK installed via Homebrew at build time. Periodically update your SDK to pick up runtime stability and security fixes:

brew upgrade dotnet

Then re-run the install script to rebuild with the updated runtime.

Logs and Debugging

Application logs are in ~/network-optimizer/logs/:

# Follow live logs
tail -f ~/network-optimizer/logs/stdout.log

# View errors
tail -f ~/network-optimizer/logs/stderr.log

# Search for specific events
grep "UniFi" ~/network-optimizer/logs/stdout.log | tail -20

Enable Debug Logging

For more detailed logs, edit ~/network-optimizer/start.sh and add:

# Debug logging for Network Optimizer application code only (recommended):
export Logging__LogLevel__NetworkOptimizer=Debug

# Or debug everything (verbose - includes framework/EF Core noise):
export Logging__LogLevel__Default=Debug

Then restart the service:

launchctl unload ~/Library/LaunchAgents/net.ozarkconnect.networkoptimizer.plist
launchctl load ~/Library/LaunchAgents/net.ozarkconnect.networkoptimizer.plist

Remember to set it back to Information when done - debug logging is verbose.

Log Rotation

Logs are not rotated automatically. To clear them:

# Truncate without restarting
: > ~/network-optimizer/logs/stdout.log
: > ~/network-optimizer/logs/stderr.log

Troubleshooting

Previous sudo Installation

If you previously ran the install script with sudo, files and processes end up owned by root, which breaks future installs and upgrades. The install script detects this automatically and offers to fix it. Just run the script normally (without sudo):

./scripts/install-macos-native.sh

It will prompt for your password once to clean up root-owned files and kill root-owned processes, then continue the installation as your regular user.

Never run the install script with sudo. Everything installs to your home directory and does not need root access.

Reset Admin Password

If you forget the admin password, use the reset script:

curl -fsSL https://raw.githubusercontent.com/Ozark-Connect/NetworkOptimizer/main/scripts/reset-password.sh | bash

The script auto-detects the macOS native installation, clears the password, restarts the service, and displays the new temporary password.

Manual fallback:

# Stop the service
launchctl unload ~/Library/LaunchAgents/net.ozarkconnect.networkoptimizer.plist

# Clear the password
sqlite3 ~/Library/Application\ Support/NetworkOptimizer/network_optimizer.db \
    "UPDATE AdminSettings SET Password = NULL, Enabled = 0;"

# Restart
launchctl load ~/Library/LaunchAgents/net.ozarkconnect.networkoptimizer.plist

# View the new password
grep "Password:" ~/network-optimizer/logs/stdout.log | tail -1

Uninstalling

# Stop and remove the service
launchctl unload ~/Library/LaunchAgents/net.ozarkconnect.networkoptimizer.plist
rm ~/Library/LaunchAgents/net.ozarkconnect.networkoptimizer.plist

# Remove application files
rm -rf ~/network-optimizer

# Remove data (database, keys) - optional
rm -rf ~/Library/Application\ Support/NetworkOptimizer