Skip to content

MACOS-INSTALLATION.md

Latest commit

 

History

History
124 lines (86 loc) · 3.54 KB

MACOS-INSTALLATION.md

File metadata and controls

124 lines (86 loc) · 3.54 KB

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)
  • LOG_LEVEL / APP_LOG_LEVEL - Logging verbosity

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 auto-generated admin password:

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.

Troubleshooting

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