usda-vision/docs/HOST_IP_CONFIGURATION.md

Host IP Configuration for Supabase

Overview

The Supabase config.toml file uses the site_url setting to configure authentication redirects. Instead of hardcoding the host IP address, we now use environment variables that are automatically detected from the host machine.

Problem

Previously, the site_url was hardcoded (e.g., http://exp-dash:3000), which:

• Doesn't work when the host IP changes
• Requires manual updates for different environments
• Is not portable across different machines

Solution

We now use the HOST_SITE_URL environment variable, which is automatically detected using the host machine's IP address.

Usage

Automatic Detection (Recommended)

Use the provided scripts to automatically detect and set the host IP:

# Option 1: Source the environment setup script
source ./scripts/set-host-env.sh

# Then run Supabase CLI commands normally
supabase start
supabase db reset

Or use the wrapper script that does this automatically:

# Use the wrapper script for Supabase CLI commands
./scripts/supabase-with-env.sh start
./scripts/supabase-with-env.sh db reset

Manual Configuration

If automatic detection doesn't work or you want to use a specific IP:

# Set the environment variable manually
export HOST_SITE_URL="http://192.168.1.100:3000"

# Or with a different port
export HOST_SITE_URL="http://192.168.1.100:8080"

# Then run Supabase commands
supabase start

For Docker Compose

If you're using Docker Compose and need to set this for Supabase CLI commands run on the host:

# Before running docker compose or Supabase CLI
export HOST_SITE_URL="http://$(./scripts/get-host-ip.sh):3000"
docker compose up -d

Or add it to your shell profile (~/.bashrc or ~/.zshrc):

# Add to ~/.bashrc or ~/.zshrc
export HOST_SITE_URL="http://$(/path/to/USDA-VISION/scripts/get-host-ip.sh):3000"

How It Works

1. IP Detection Script (scripts/get-host-ip.sh):

   • Tries multiple methods to detect the host IP
   • Works both inside Docker containers and on the host machine
   • Falls back to 127.0.0.1 if detection fails

2. Environment Setup Script (scripts/set-host-env.sh):

   • Calls the IP detection script
   • Sets HOST_SITE_URL environment variable
   • Can be sourced to set the variable in your current shell

3. Supabase Wrapper Script (scripts/supabase-with-env.sh):

   • Automatically sets HOST_SITE_URL before running Supabase CLI
   • Transparent wrapper - just use it instead of supabase command

4. Config File (supabase/config.toml):

   • Uses env(HOST_SITE_URL) to read the environment variable
   • Supabase CLI automatically substitutes the value

Detection Methods

The IP detection script tries these methods in order:

1. Default Gateway (for containers): Gets the gateway IP which is typically the host
2. host.docker.internal: Uses Docker's special DNS name (if available)
3. Network Interface: Checks common network interfaces (eth0, enp0s8, etc.)
4. Hostname Resolution: Uses hostname -I to get the host IP
5. Fallback: Returns 127.0.0.1 if all methods fail

Troubleshooting

IP Detection Fails

If the script can't detect the IP:

1. Check network interfaces:

   ip addr show
   # or
   ifconfig
   

2. Manually set the IP:

   export HOST_SITE_URL="http://YOUR_ACTUAL_IP:3000"
   

3. Verify the IP is accessible:

   ping $(./scripts/get-host-ip.sh)
   

Supabase CLI Doesn't Use the Variable

Make sure you:

1. Set HOST_SITE_URL before running Supabase CLI
2. Run Supabase CLI from the project root (where supabase/ directory is)
3. Check that config.toml uses env(HOST_SITE_URL) syntax

Port Mismatch

If your React app runs on a different port, adjust the port in the URL:

export HOST_SITE_URL="http://$(./scripts/get-host-ip.sh):8080"

Example Workflow

# 1. Navigate to project root
cd /path/to/USDA-VISION

# 2. Set the environment variable (automatic detection)
source ./scripts/set-host-env.sh

# 3. Verify it's set
echo $HOST_SITE_URL
# Output: http://192.168.1.100:3000

# 4. Start Supabase
supabase start

# Or use the wrapper script (does steps 2-4 automatically)
./scripts/supabase-with-env.sh start

Integration with Docker Compose

If you're running Supabase via Docker Compose (not CLI), the containers use their own networking. The HOST_SITE_URL is primarily for Supabase CLI commands that run on the host machine.

For container-to-container communication, use Docker service names (e.g., http://web:8080).

For browser-based redirects from Supabase Auth back to your React app, use the actual host IP that the browser can access.