watch-finished-turbo/docs/MIGRATION_API_PROXY.md

Migration Guide: API Proxy Update

What Changed

The web application now uses a Next.js API proxy by default instead of direct client-to-API connections. This provides better security and enables remote access.

Benefits

• Remote Access: Access the web UI from anywhere - it will automatically connect to the API through the proxy
• Security: Only port 3000 needs to be exposed; API port 3001 stays internal
• No CORS Issues: Single-origin requests eliminate cross-origin problems
• Simpler Deployment: One port to expose and configure

How to Update

For Local Development

1. Update your .env.local file:

   cd apps/web
   # Remove or comment out the old direct API URL
   # NEXT_PUBLIC_WATCH_FINISHED_API=http://localhost:3001

   # Add the backend API URL for the Next.js server
   API_URL=http://localhost:3001

1. Restart the development servers:

   # From project root
   pnpm run dev

1. Access the web UI:
   • Open http://localhost:3000
   • The web UI will automatically proxy requests to the API at http://localhost:3001

For Docker Deployment

1. Rebuild your Docker images:

   docker-compose build

1. Update port mappings (if you customized docker-compose.yml):

   • Only expose port 3000 externally
   • Port 3001 is now internal only

2. Run the containers:

   docker-compose up
   

   For Remote Access

   Before (didn't work remotely):

   • Web UI at http://192.168.1.100:3000
   • Tried to connect to API at http://localhost:3001 (failed from remote)

   After (works remotely):

   • Web UI at http://192.168.1.100:3000
   • API requests automatically proxied through the web server
   • WebSocket connections also proxied

   Advanced: Direct API Connection (Optional)

   If you need the old behavior (direct client-to-API), you can bypass the proxy:

   # In apps/web/.env.local
   NEXT_PUBLIC_WATCH_FINISHED_API=http://your-api-server:3001
   API_URL=http://localhost:3001
   

This is useful for:

• Development across multiple machines
• Custom API server locations
• Debugging proxy issues

Architecture Changes

Before

Browser → http://localhost:3001/api/* (direct)
Browser → ws://localhost:3001/socket.io (direct)

After (Default)

Browser → http://localhost:3000/api/* → Next.js Proxy → http://localhost:3001/*
Browser → ws://localhost:3000/socket.io → Next.js Proxy → ws://localhost:3001/socket.io

After (With NEXT_PUBLIC_WATCH_FINISHED_API set)

Browser → http://localhost:3001/api/* (direct, bypasses proxy)
Browser → ws://localhost:3001/socket.io (direct, bypasses proxy)

Troubleshooting

Web UI shows "Connection Error"

1. Check that the API service is running on port 3001
2. Verify API_URL in your environment matches where the API is running
3. Check the browser console for specific error messages

WebSocket not connecting

1. Make sure both web and service are running
2. Check browser console for WebSocket connection errors
3. Verify the proxy is configured in next.config.ts

Remote access still not working

1. Ensure firewall allows port 3000
2. Use the machine's IP address or hostname, not "localhost"
3. Check that API_URL points to the correct internal API location

Rollback

To revert to the old behavior temporarily:

# In apps/web/.env.local
NEXT_PUBLIC_WATCH_FINISHED_API=http://localhost:3001

This will bypass the proxy and connect directly to the API.