Tunneling Guide (Ngrok)

This guide explains how to expose your local Backend server to the internet using Ngrok. This is essential for testing features like Google OAuth, Webhooks, and Mobile App Integration.

📋 Prerequisites

• Python 3.12+ installed
• uv package manager installed
• An Ngrok account (Sign up at https://ngrok.com/)

🚀 Step-by-Step Setup

1. Install Ngrok If you are on macOS, install using Homebrew: brew install ngrok/ngrok/ngrok

For other operating systems, download from: https://ngrok.com/download

1. Authenticate Ngrok Ngrok requires an authtoken to function.

Steps:

1. Log in to https://dashboard.ngrok.com/
2. Copy your Authtoken
3. Run: ngrok config add-authtoken <YOUR_AUTHTOKEN>
4. Run the Backend & Tunnel

We provide a script called run_ngrok.sh to start both the FastAPI server and Ngrok.

Run: chmod +x run_ngrok.sh ./run_ngrok.sh

What this script does:

1. Kills processes on port 8000
2. Starts FastAPI using uv run uvicorn
3. Starts an Ngrok tunnel on port 8000
4. Get Your Public URL

After running, Ngrok shows something like:

Forwarding https://xxxx-xxxx-xxxx.ngrok-free.app -> http://localhost:8000

Copy the https URL.

1. Update Environment Variables

Update your .env file with the Ngrok URL:

GOOGLE_REDIRECT_URI=https://xxxx-xxxx-xxxx.ngrok-free.app/api/v1/auth/google/callback GOOGLE_CALENDAR_REDIRECT_URI=https://xxxx-xxxx-xxxx.ngrok-free.app/api/v1/integrations/calendar/callback

🛠 Troubleshooting

Port Already in Use If you see: [Errno 48] Address already in use

Run: lsof -t -i :8000 | xargs kill -9

Invalid Authtoken Make sure you added the correct token using: ngrok config add-authtoken

Ngrok Warning Page To bypass the warning page, include this header in requests: ngrok-skip-browser-warning: any-value

🔒 Security Note

Do not commit ngrok.yml or your Authtoken to a public repository. Keep your .env file in .gitignore.