Skip to main content

Using dorcha-gateway on macOS

We support all macOS versions that are currently receiving Apple support on both Intel and Apple Silicon.

Prerequisites​

  • macOS 10.15 (Catalina) or later
  • Root or sudo access for installation
  • At least 512MB RAM
  • Network access for configuration and updates
  • Homebrew (recommended for easy installation)

Installation​

# Extract
tar -xzf dorcha-gateway-macos-[intel|apple].tar.gz

# Move to a directory in your PATH
sudo mv dorcha-gateway /usr/local/bin/
sudo chmod +x /usr/local/bin/dorcha-gateway

# Verify installation
dorcha-gateway --version

Configuration​

  1. Create configuration directory:
sudo mkdir -p /usr/local/etc/dorcha
sudo mkdir -p /usr/local/var/log/dorcha
sudo mkdir -p /usr/local/var/lib/dorcha/keys
  1. Copy example configuration:
sudo cp example-configs/config.http.example.json /usr/local/etc/dorcha/dorcha-gateway-config.json
sudo nano /usr/local/etc/dorcha/dorcha-gateway-config.json

Running dorcha-gateway​

Option 1: Direct Execution​

# Run directly
dorcha-gateway -config /usr/local/etc/dorcha/dorcha-gateway-config.json

# Or with environment variables
DORCHA_CONFIG_PATH=/usr/local/etc/dorcha/dorcha-gateway-config.json dorcha-gateway

Option 2: LaunchAgent (Background Service)​

Create ~/Library/LaunchAgents/com.dorcha.gateway.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.dorcha.gateway</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/dorcha-gateway</string>
        <string>-config</string>
        <string>/usr/local/etc/dorcha/dorcha-gateway-config.json</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/usr/local/var/log/dorcha/stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/usr/local/var/log/dorcha/stderr.log</string>
</dict>
</plist>

Load and start the service:

# Load the service
launchctl load ~/Library/LaunchAgents/com.dorcha.gateway.plist

# Start the service
launchctl start com.dorcha.gateway

# Check status
launchctl list | grep dorcha

Verification​

Check if the gateway is running:

# Test health endpoint
curl http://localhost:3128/health

# Check process
ps aux | grep dorcha-gateway

# Check logs
tail -f /usr/local/var/log/dorcha/stdout.log

Troubleshooting​

Common Issues​

  • Permission denied: Ensure the binary is executable with chmod +x
  • Port already in use: Check if port 3128 is available with lsof -i :3128 (same for port 3129)
  • Configuration errors: Validate JSON syntax in your config file
  • LaunchAgent not working: Check launchctl list and logs

Logs and Debugging​

  • LaunchAgent logs: /usr/local/var/log/dorcha/
  • System logs: log show --predicate 'process == "dorcha-gateway"'
  • Manual execution: Run directly to see immediate output

Performance Tuning​

  • Memory limits: Monitor with Activity Monitor
  • Network: Use netstat -an | grep 3128 to check connections
  • File descriptors: Increase limits if needed for high concurrency