Skip to content

QUICK-START-HTTPS.md

Latest commit

 

History

History
133 lines (87 loc) · 3.93 KB

QUICK-START-HTTPS.md

File metadata and controls

133 lines (87 loc) · 3.93 KB
Raw

Quick Start: HTTPS for Mobile Testing

When accessing the web app from an iPhone or iPad, Safari requires HTTPS (or localhost) to grant camera/microphone access. The simplest way to get a trusted HTTPS URL on your phone is to use a tunneling tool that exposes your local servers over HTTPS.

Below are two easy, free options. Option A is recommended.

Option A — Cloudflare Tunnel (recommended)

Cloudflare can create a temporary, public, trusted HTTPS URL for any local port. No account is required for the quick “trycloudflare.com” tunnel.

Prerequisites (macOS):

  • Homebrew installed

Steps:

  1. Install the CLI
brew install cloudflared
  1. Start your local servers (in separate terminals)

You can use the provided start script in the repo root in two terminals or your usual workflow.

  1. Create a public HTTPS URL for the backend
cloudflared tunnel --url http://127.0.0.1:8000
  • Copy the printed https://…trycloudflare.com URL (example: https://abcde.trycloudflare.com)
  • Update the frontend environment to point to the backend HTTPS URL to avoid mixed content:

Edit frontend/.env.local and set:

NEXT_PUBLIC_API_URL=https://abcde.trycloudflare.com
  1. Create a public HTTPS URL for the frontend

In a new terminal:

cloudflared tunnel --url http://127.0.0.1:3000
  • Open the printed HTTPS URL on your iPhone.
  • On first tap inside the camera viewport, Safari will start the camera (we already wired the user-gesture handling).

Notes:

  • Mixed content: If the frontend is HTTPS but the backend is HTTP, the browser will block requests. That’s why step 3 sets the backend to an HTTPS tunnel too.
  • CORS: The backend is configured to allow requests from any origin in development, so cross-origin calls from your frontend tunnel to your backend tunnel will work.

Troubleshooting (Cloudflare Tunnel):

  • If you see a timeout like failed to request quick Tunnel: context deadline exceeded:
    • Force IPv4 (some networks break IPv6) and prefer IPv4 loopback: 
       cloudflared --edge-ip-version 4 tunnel --url http://127.0.0.1:8000
    • Increase logging to see details: 
       cloudflared tunnel --url http://localhost:8000 --loglevel debug
    • University/enterprise Wi‑Fi may block trycloudflare.com. In that case, use the ngrok fallback below.

Option B — ngrok

ngrok also provides quick HTTPS URLs to your local ports.

  1. Install
brew install ngrok/ngrok/ngrok
  1. Start tunnels
  • Backend:
ngrok http 8000

Copy the https URL and set it in frontend/.env.local:

NEXT_PUBLIC_API_URL=https://your-backend-subdomain.ngrok.io
  • Frontend:
ngrok http 3000

Open the HTTPS URL shown for the frontend on your phone.

Tips:

  • You can reserve subdomains with a (free) ngrok account for stable URLs.

Optional — Local HTTPS with self-signed cert (desktop-only)

You can run the Next.js dev server over HTTPS locally using a self-signed certificate, but it won’t be trusted by iOS without extra steps. This is useful mainly for desktop testing.

  • Next.js supports an experimental HTTPS dev flag:
# Not recommended for iOS devices unless you install and trust the cert on the device
next dev --experimental-https
  • Alternatively, use mkcert + a reverse proxy like Caddy to terminate TLS locally. To use it on an iPhone, you must install and trust the local CA on the device (Settings > General > About > Certificate Trust Settings). This is more involved than using a tunnel.

Verification Checklist

  • Frontend opens on your phone using an HTTPS URL
  • frontend/.env.local points to an HTTPS backend URL (same or different domain)
  • Tapping the viewport starts the camera (user gesture requirement)
  • Console shows successful /health and inference requests

If you hit any issues, share the tunnel URLs and console/network logs and we’ll debug quickly.