docs(self-hosting): mark NEXT_PUBLIC_SOCKET_URL as optional

waleedlatif1 · waleedlatif1 · commit 36d50ea20ae5 · 2026-04-30T19:12:38.000-07:00
The page-origin fallback in getSocketUrl() means self-hosters no longer
need to set NEXT_PUBLIC_SOCKET_URL when realtime is on the same origin
as the app. Update docs to reflect this:

- Remove NEXT_PUBLIC_SOCKET_URL from .env scaffolding examples in
  docker.mdx, platforms.mdx, environment-variables.mdx
- Mark the variable as Optional in the env vars table with the new
  default behavior described
- Update troubleshooting to point at reverse-proxy /socket.io routing
  rather than the env var
- Flip dev docker-compose defaults (local, ollama, devcontainer) from
  http://localhost:3002 to empty for consistency with prod.yml; the
  in-code localhost fallback handles the dev case identically

Applied across all 6 documentation languages (en/fr/de/ja/es/zh).
diff --git a/.claude/scheduled_tasks.lock b/.claude/scheduled_tasks.lock
@@ -0,0 +1 @@
+{"sessionId":"f9b861f8-99ed-4e19-8a09-150e364ee5ad","pid":64490,"acquiredAt":1777596917401}
diff --git a/.devcontainer/docker-compose.yml b/.devcontainer/docker-compose.yml
@@ -21,7 +21,7 @@ services:
       - COPILOT_API_KEY=${COPILOT_API_KEY}
       - SIM_AGENT_API_URL=${SIM_AGENT_API_URL}
       - OLLAMA_URL=${OLLAMA_URL:-http://localhost:11434}
-      - NEXT_PUBLIC_SOCKET_URL=${NEXT_PUBLIC_SOCKET_URL:-http://localhost:3002}
+      - NEXT_PUBLIC_SOCKET_URL=${NEXT_PUBLIC_SOCKET_URL:-}
       - BUN_INSTALL_CACHE_DIR=/home/bun/.bun/cache
     depends_on:
       db:
diff --git a/apps/docs/content/docs/de/self-hosting/docker.mdx b/apps/docs/content/docs/de/self-hosting/docker.mdx
@@ -29,7 +29,6 @@ ENCRYPTION_KEY=$(openssl rand -hex 32)
 INTERNAL_API_SECRET=$(openssl rand -hex 32)
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
 BETTER_AUTH_URL=https://sim.yourdomain.com
-NEXT_PUBLIC_SOCKET_URL=https://sim.yourdomain.com
 EOF
 ```
 
diff --git a/apps/docs/content/docs/de/self-hosting/environment-variables.mdx b/apps/docs/content/docs/de/self-hosting/environment-variables.mdx
@@ -15,7 +15,7 @@ import { Callout } from 'fumadocs-ui/components/callout'
 | `ENCRYPTION_KEY` | Verschlüsselungsschlüssel (32 Hex-Zeichen): `openssl rand -hex 32` |
 | `INTERNAL_API_SECRET` | Internes API-Secret (32 Hex-Zeichen): `openssl rand -hex 32` |
 | `NEXT_PUBLIC_APP_URL` | Öffentliche App-URL |
-| `NEXT_PUBLIC_SOCKET_URL` | WebSocket-URL (Standard: `http://localhost:3002`) |
+| `NEXT_PUBLIC_SOCKET_URL` | Optional. WebSocket-URL — verwendet standardmäßig den Seitenursprung; nur setzen, wenn Realtime auf einem separaten Host läuft. |
 
 ## KI-Anbieter
 
@@ -80,7 +80,6 @@ BETTER_AUTH_URL=https://sim.yourdomain.com
 ENCRYPTION_KEY=<openssl rand -hex 32>
 INTERNAL_API_SECRET=<openssl rand -hex 32>
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
-NEXT_PUBLIC_SOCKET_URL=https://sim.yourdomain.com
 OPENAI_API_KEY=sk-...
 ```
 
diff --git a/apps/docs/content/docs/de/self-hosting/platforms.mdx b/apps/docs/content/docs/de/self-hosting/platforms.mdx
@@ -77,7 +77,6 @@ ENCRYPTION_KEY=$(openssl rand -hex 32)
 INTERNAL_API_SECRET=$(openssl rand -hex 32)
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
 BETTER_AUTH_URL=https://sim.yourdomain.com
-NEXT_PUBLIC_SOCKET_URL=https://sim.yourdomain.com
 EOF
 
 # Start
diff --git a/apps/docs/content/docs/de/self-hosting/troubleshooting.mdx b/apps/docs/content/docs/de/self-hosting/troubleshooting.mdx
@@ -27,7 +27,7 @@ OLLAMA_URL=http://192.168.1.x:11434           # Linux (use actual IP)
 
 ## WebSocket/Echtzeit funktioniert nicht
 
-1. Prüfen Sie, ob `NEXT_PUBLIC_SOCKET_URL` mit Ihrer Domain übereinstimmt
+1. Stellen Sie sicher, dass der Reverse Proxy `/socket.io` an den Realtime-Service (Standardport 3002) weiterleitet. `NEXT_PUBLIC_SOCKET_URL` ist nur erforderlich, wenn Realtime auf einem separaten Host läuft.
 2. Überprüfen Sie, ob der Echtzeit-Dienst läuft: `docker compose ps realtime`
 3. Stellen Sie sicher, dass der Reverse-Proxy WebSocket-Upgrades weiterleitet (siehe [Docker-Anleitung](/self-hosting/docker))
 
diff --git a/apps/docs/content/docs/en/self-hosting/docker.mdx b/apps/docs/content/docs/en/self-hosting/docker.mdx
@@ -30,7 +30,6 @@ ENCRYPTION_KEY=$(openssl rand -hex 32)
 INTERNAL_API_SECRET=$(openssl rand -hex 32)
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
 BETTER_AUTH_URL=https://sim.yourdomain.com
-NEXT_PUBLIC_SOCKET_URL=https://sim.yourdomain.com
 EOF
 ```
 
diff --git a/apps/docs/content/docs/en/self-hosting/environment-variables.mdx b/apps/docs/content/docs/en/self-hosting/environment-variables.mdx
@@ -15,7 +15,7 @@ import { Callout } from 'fumadocs-ui/components/callout'
 | `ENCRYPTION_KEY` | Encryption key (32 hex chars): `openssl rand -hex 32` |
 | `INTERNAL_API_SECRET` | Internal API secret (32 hex chars): `openssl rand -hex 32` |
 | `NEXT_PUBLIC_APP_URL` | Public app URL |
-| `NEXT_PUBLIC_SOCKET_URL` | WebSocket URL (default: `http://localhost:3002`) |
+| `NEXT_PUBLIC_SOCKET_URL` | Optional. WebSocket URL — defaults to the page origin; set only if realtime is on a separate host. |
 
 ## AI Providers
 
@@ -80,7 +80,6 @@ BETTER_AUTH_URL=https://sim.yourdomain.com
 ENCRYPTION_KEY=<openssl rand -hex 32>
 INTERNAL_API_SECRET=<openssl rand -hex 32>
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
-NEXT_PUBLIC_SOCKET_URL=https://sim.yourdomain.com
 OPENAI_API_KEY=sk-...
 ```
 
diff --git a/apps/docs/content/docs/en/self-hosting/platforms.mdx b/apps/docs/content/docs/en/self-hosting/platforms.mdx
@@ -70,7 +70,6 @@ ENCRYPTION_KEY=$(openssl rand -hex 32)
 INTERNAL_API_SECRET=$(openssl rand -hex 32)
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
 BETTER_AUTH_URL=https://sim.yourdomain.com
-NEXT_PUBLIC_SOCKET_URL=https://sim.yourdomain.com
 EOF
 
 # Start
diff --git a/apps/docs/content/docs/en/self-hosting/troubleshooting.mdx b/apps/docs/content/docs/en/self-hosting/troubleshooting.mdx
@@ -27,7 +27,7 @@ OLLAMA_URL=http://192.168.1.x:11434           # Linux (use actual IP)
 
 ## WebSocket/Realtime Not Working
 
-1. Check `NEXT_PUBLIC_SOCKET_URL` matches your domain
+1. Verify reverse proxy routes `/socket.io` to the realtime service (default port 3002). `NEXT_PUBLIC_SOCKET_URL` is only needed if realtime is on a separate host.
 2. Verify realtime service is running: `docker compose ps realtime`
 3. Ensure reverse proxy passes WebSocket upgrades (see [Docker guide](/self-hosting/docker))
 
diff --git a/apps/docs/content/docs/es/self-hosting/docker.mdx b/apps/docs/content/docs/es/self-hosting/docker.mdx
@@ -29,7 +29,6 @@ ENCRYPTION_KEY=$(openssl rand -hex 32)
 INTERNAL_API_SECRET=$(openssl rand -hex 32)
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
 BETTER_AUTH_URL=https://sim.yourdomain.com
-NEXT_PUBLIC_SOCKET_URL=https://sim.yourdomain.com
 EOF
 ```
 
diff --git a/apps/docs/content/docs/es/self-hosting/environment-variables.mdx b/apps/docs/content/docs/es/self-hosting/environment-variables.mdx
@@ -15,7 +15,7 @@ import { Callout } from 'fumadocs-ui/components/callout'
 | `ENCRYPTION_KEY` | Clave de cifrado (32 caracteres hex): `openssl rand -hex 32` |
 | `INTERNAL_API_SECRET` | Secreto de API interna (32 caracteres hex): `openssl rand -hex 32` |
 | `NEXT_PUBLIC_APP_URL` | URL pública de la aplicación |
-| `NEXT_PUBLIC_SOCKET_URL` | URL de WebSocket (predeterminado: `http://localhost:3002`) |
+| `NEXT_PUBLIC_SOCKET_URL` | Opcional. URL de WebSocket — predetermina al origen de la página; configúrala solo si realtime está en un host separado. |
 
 ## Proveedores de IA
 
@@ -80,7 +80,6 @@ BETTER_AUTH_URL=https://sim.yourdomain.com
 ENCRYPTION_KEY=<openssl rand -hex 32>
 INTERNAL_API_SECRET=<openssl rand -hex 32>
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
-NEXT_PUBLIC_SOCKET_URL=https://sim.yourdomain.com
 OPENAI_API_KEY=sk-...
 ```
 
diff --git a/apps/docs/content/docs/es/self-hosting/platforms.mdx b/apps/docs/content/docs/es/self-hosting/platforms.mdx
@@ -77,7 +77,6 @@ ENCRYPTION_KEY=$(openssl rand -hex 32)
 INTERNAL_API_SECRET=$(openssl rand -hex 32)
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
 BETTER_AUTH_URL=https://sim.yourdomain.com
-NEXT_PUBLIC_SOCKET_URL=https://sim.yourdomain.com
 EOF
 
 # Start
diff --git a/apps/docs/content/docs/es/self-hosting/troubleshooting.mdx b/apps/docs/content/docs/es/self-hosting/troubleshooting.mdx
@@ -27,7 +27,7 @@ OLLAMA_URL=http://192.168.1.x:11434           # Linux (use actual IP)
 
 ## WebSocket/Tiempo real no funciona
 
-1. Comprueba que `NEXT_PUBLIC_SOCKET_URL` coincida con tu dominio
+1. Verifica que el proxy inverso enrute `/socket.io` al servicio realtime (puerto 3002 por defecto). `NEXT_PUBLIC_SOCKET_URL` solo es necesaria si realtime está en un host separado.
 2. Verifica que el servicio en tiempo real esté funcionando: `docker compose ps realtime`
 3. Asegúrate de que el proxy inverso pase las actualizaciones de WebSocket (consulta la [guía de Docker](/self-hosting/docker))
 
diff --git a/apps/docs/content/docs/fr/self-hosting/docker.mdx b/apps/docs/content/docs/fr/self-hosting/docker.mdx
@@ -29,7 +29,6 @@ ENCRYPTION_KEY=$(openssl rand -hex 32)
 INTERNAL_API_SECRET=$(openssl rand -hex 32)
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
 BETTER_AUTH_URL=https://sim.yourdomain.com
-NEXT_PUBLIC_SOCKET_URL=https://sim.yourdomain.com
 EOF
 ```
 
diff --git a/apps/docs/content/docs/fr/self-hosting/environment-variables.mdx b/apps/docs/content/docs/fr/self-hosting/environment-variables.mdx
@@ -15,7 +15,7 @@ import { Callout } from 'fumadocs-ui/components/callout'
 | `ENCRYPTION_KEY` | Clé de chiffrement (32 caractères hexadécimaux) : `openssl rand -hex 32` |
 | `INTERNAL_API_SECRET` | Secret API interne (32 caractères hexadécimaux) : `openssl rand -hex 32` |
 | `NEXT_PUBLIC_APP_URL` | URL publique de l'application |
-| `NEXT_PUBLIC_SOCKET_URL` | URL WebSocket (par défaut : `http://localhost:3002`) |
+| `NEXT_PUBLIC_SOCKET_URL` | Optionnel. URL WebSocket — utilise par défaut l'origine de la page ; à définir uniquement si realtime est sur un hôte séparé. |
 
 ## Fournisseurs d'IA
 
@@ -80,7 +80,6 @@ BETTER_AUTH_URL=https://sim.yourdomain.com
 ENCRYPTION_KEY=<openssl rand -hex 32>
 INTERNAL_API_SECRET=<openssl rand -hex 32>
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
-NEXT_PUBLIC_SOCKET_URL=https://sim.yourdomain.com
 OPENAI_API_KEY=sk-...
 ```
 
diff --git a/apps/docs/content/docs/fr/self-hosting/platforms.mdx b/apps/docs/content/docs/fr/self-hosting/platforms.mdx
@@ -77,7 +77,6 @@ ENCRYPTION_KEY=$(openssl rand -hex 32)
 INTERNAL_API_SECRET=$(openssl rand -hex 32)
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
 BETTER_AUTH_URL=https://sim.yourdomain.com
-NEXT_PUBLIC_SOCKET_URL=https://sim.yourdomain.com
 EOF
 
 # Start
diff --git a/apps/docs/content/docs/fr/self-hosting/troubleshooting.mdx b/apps/docs/content/docs/fr/self-hosting/troubleshooting.mdx
@@ -27,7 +27,7 @@ OLLAMA_URL=http://192.168.1.x:11434           # Linux (use actual IP)
 
 ## WebSocket/Temps réel ne fonctionne pas
 
-1. Vérifiez que `NEXT_PUBLIC_SOCKET_URL` correspond à votre domaine
+1. Vérifiez que le reverse proxy route `/socket.io` vers le service realtime (port 3002 par défaut). `NEXT_PUBLIC_SOCKET_URL` n'est nécessaire que si realtime est sur un hôte séparé.
 2. Vérifiez que le service temps réel est en cours d'exécution : `docker compose ps realtime`
 3. Assurez-vous que le proxy inverse transmet les mises à niveau WebSocket (voir [Guide Docker](/self-hosting/docker))
 
diff --git a/apps/docs/content/docs/ja/self-hosting/docker.mdx b/apps/docs/content/docs/ja/self-hosting/docker.mdx
@@ -29,7 +29,6 @@ ENCRYPTION_KEY=$(openssl rand -hex 32)
 INTERNAL_API_SECRET=$(openssl rand -hex 32)
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
 BETTER_AUTH_URL=https://sim.yourdomain.com
-NEXT_PUBLIC_SOCKET_URL=https://sim.yourdomain.com
 EOF
 ```
 
diff --git a/apps/docs/content/docs/ja/self-hosting/environment-variables.mdx b/apps/docs/content/docs/ja/self-hosting/environment-variables.mdx
@@ -15,7 +15,7 @@ import { Callout } from 'fumadocs-ui/components/callout'
 | `ENCRYPTION_KEY` | 暗号化キー（32桁の16進数）: `openssl rand -hex 32` |
 | `INTERNAL_API_SECRET` | 内部APIシークレット（32桁の16進数）: `openssl rand -hex 32` |
 | `NEXT_PUBLIC_APP_URL` | 公開アプリURL |
-| `NEXT_PUBLIC_SOCKET_URL` | WebSocket URL（デフォルト: `http://localhost:3002`） |
+| `NEXT_PUBLIC_SOCKET_URL` | 任意。WebSocket URL — デフォルトはページのオリジン。realtime が別ホストの場合のみ設定。 |
 
 ## AIプロバイダー
 
@@ -80,7 +80,6 @@ BETTER_AUTH_URL=https://sim.yourdomain.com
 ENCRYPTION_KEY=<openssl rand -hex 32>
 INTERNAL_API_SECRET=<openssl rand -hex 32>
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
-NEXT_PUBLIC_SOCKET_URL=https://sim.yourdomain.com
 OPENAI_API_KEY=sk-...
 ```
 
diff --git a/apps/docs/content/docs/ja/self-hosting/platforms.mdx b/apps/docs/content/docs/ja/self-hosting/platforms.mdx
@@ -77,7 +77,6 @@ ENCRYPTION_KEY=$(openssl rand -hex 32)
 INTERNAL_API_SECRET=$(openssl rand -hex 32)
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
 BETTER_AUTH_URL=https://sim.yourdomain.com
-NEXT_PUBLIC_SOCKET_URL=https://sim.yourdomain.com
 EOF
 
 # Start
diff --git a/apps/docs/content/docs/ja/self-hosting/troubleshooting.mdx b/apps/docs/content/docs/ja/self-hosting/troubleshooting.mdx
@@ -27,7 +27,7 @@ OLLAMA_URL=http://192.168.1.x:11434           # Linux (use actual IP)
 
 ## WebSocket/リアルタイム機能が動作しない
 
-1. `NEXT_PUBLIC_SOCKET_URL` がドメインと一致しているか確認する
+1. リバースプロキシが `/socket.io` を realtime サービス（デフォルトポート 3002）にルーティングしているか確認してください。`NEXT_PUBLIC_SOCKET_URL` は realtime が別ホストにある場合のみ必要です。
 2. リアルタイムサービスが実行されているか確認する: `docker compose ps realtime`
 3. リバースプロキシがWebSocketアップグレードを通過させていることを確認する（[Dockerガイド](/self-hosting/docker)を参照）
 
diff --git a/apps/docs/content/docs/zh/self-hosting/docker.mdx b/apps/docs/content/docs/zh/self-hosting/docker.mdx
@@ -29,7 +29,6 @@ ENCRYPTION_KEY=$(openssl rand -hex 32)
 INTERNAL_API_SECRET=$(openssl rand -hex 32)
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
 BETTER_AUTH_URL=https://sim.yourdomain.com
-NEXT_PUBLIC_SOCKET_URL=https://sim.yourdomain.com
 EOF
 ```
 
diff --git a/apps/docs/content/docs/zh/self-hosting/environment-variables.mdx b/apps/docs/content/docs/zh/self-hosting/environment-variables.mdx
@@ -15,7 +15,7 @@ import { Callout } from 'fumadocs-ui/components/callout'
 | `ENCRYPTION_KEY` | 加密密钥（32 个十六进制字符）：`openssl rand -hex 32` |
 | `INTERNAL_API_SECRET` | 内部 API 密钥（32 个十六进制字符）：`openssl rand -hex 32` |
 | `NEXT_PUBLIC_APP_URL` | 公共应用程序 URL |
-| `NEXT_PUBLIC_SOCKET_URL` | WebSocket URL（默认值：`http://localhost:3002`） |
+| `NEXT_PUBLIC_SOCKET_URL` | 可选。WebSocket URL — 默认使用页面来源；仅当 realtime 部署在独立主机时才需要设置。 |
 
 ## AI 提供商
 
@@ -80,7 +80,6 @@ BETTER_AUTH_URL=https://sim.yourdomain.com
 ENCRYPTION_KEY=<openssl rand -hex 32>
 INTERNAL_API_SECRET=<openssl rand -hex 32>
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
-NEXT_PUBLIC_SOCKET_URL=https://sim.yourdomain.com
 OPENAI_API_KEY=sk-...
 ```
 
diff --git a/apps/docs/content/docs/zh/self-hosting/platforms.mdx b/apps/docs/content/docs/zh/self-hosting/platforms.mdx
@@ -77,7 +77,6 @@ ENCRYPTION_KEY=$(openssl rand -hex 32)
 INTERNAL_API_SECRET=$(openssl rand -hex 32)
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
 BETTER_AUTH_URL=https://sim.yourdomain.com
-NEXT_PUBLIC_SOCKET_URL=https://sim.yourdomain.com
 EOF
 
 # Start
diff --git a/apps/docs/content/docs/zh/self-hosting/troubleshooting.mdx b/apps/docs/content/docs/zh/self-hosting/troubleshooting.mdx
@@ -27,7 +27,7 @@ OLLAMA_URL=http://192.168.1.x:11434           # Linux (use actual IP)
 
 ## WebSocket/实时功能无法正常工作
 
-1. 检查 `NEXT_PUBLIC_SOCKET_URL` 是否与您的域名匹配
+1. 确认反向代理将 `/socket.io` 路由到 realtime 服务（默认端口 3002）。仅当 realtime 部署在独立主机时才需要设置 `NEXT_PUBLIC_SOCKET_URL`。
 2. 验证实时服务是否正在运行：`docker compose ps realtime`
 3. 确保反向代理支持 WebSocket 升级（参见 [Docker 指南](/self-hosting/docker)）
 
diff --git a/docker-compose.local.yml b/docker-compose.local.yml
@@ -23,7 +23,7 @@ services:
       - SIM_AGENT_API_URL=${SIM_AGENT_API_URL}
       - OLLAMA_URL=${OLLAMA_URL:-http://localhost:11434}
       - SOCKET_SERVER_URL=${SOCKET_SERVER_URL:-http://realtime:3002}
-      - NEXT_PUBLIC_SOCKET_URL=${NEXT_PUBLIC_SOCKET_URL:-http://localhost:3002}
+      - NEXT_PUBLIC_SOCKET_URL=${NEXT_PUBLIC_SOCKET_URL:-}
     depends_on:
       db:
         condition: service_healthy
diff --git a/docker-compose.ollama.yml b/docker-compose.ollama.yml
@@ -21,7 +21,7 @@ services:
       - COPILOT_API_KEY=${COPILOT_API_KEY}
       - SIM_AGENT_API_URL=${SIM_AGENT_API_URL}
       - OLLAMA_URL=http://ollama:11434
-      - NEXT_PUBLIC_SOCKET_URL=${NEXT_PUBLIC_SOCKET_URL:-http://localhost:3002}
+      - NEXT_PUBLIC_SOCKET_URL=${NEXT_PUBLIC_SOCKET_URL:-}
     depends_on:
       db:
         condition: service_healthy

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+{"sessionId":"f9b861f8-99ed-4e19-8a09-150e364ee5ad","pid":64490,"acquiredAt":1777596917401}`