Initial commit

docs/tutorials/basics/ssl-proxy-webxr.md

@@ -0,0 +1,121 @@
+# Setting Up SSL Proxy for WebXR
+
+## Overview
+
+Vuer requires secure connections for WebXR functionality. Both the web client and WebSocket connections must use TLS/SSL encryption.
+
+## Key Configuration Points
+
+### WebSocket Endpoint Setup
+Pass the secure WebSocket URL via query parameter to the web client:
+```
+https://vuer.ai?ws=wss://xxxxx.ngrok.io
+```
+
+### Static File Serving
+Update component source paths to use the correct HTTPS domain. For example, change:
+
+```python
+# Before (insecure)
+src='http://localhost:8012/static/urdf/robot.urdf'
+```
+
+To:
+
+```python
+# After (secure)
+src='https://<your-domain-with-ssl>/static/urdf/robot.urdf'
+```
+
+## Recommended Proxy Solutions
+
+### Option 1: ngrok (Recommended)
+
+ngrok converts local HTTP/WebSocket connections to secure HTTPS/WSS:
+
+- `ws://localhost:8012` → `wss://xxxx.ngrok.io`
+- `http://localhost:8012/static/` → `https://xxxx.ngrok.io/static/`
+
+**Installation:**
+Visit [ngrok's website](https://ngrok.com) for installation instructions.
+
+**Usage:**
+```bash
+ngrok http 8012
+```
+
+This will provide a secure URL like `https://xxxx.ngrok.io` that you can use for WebXR.
+
+### Option 2: localtunnel
+
+Free alternative requiring a passcode.
+
+**Installation:**
+```bash
+npm install -g localtunnel
+```
+
+**Usage:**
+```bash
+lt --port 8012
+```
+
+**Documentation:** https://localtunnel.me
+
+### Option 3: Let's Encrypt Self-Signed Certificate
+
+Generate and use your own SSL certificate.
+
+**Launch Vuer with Certificate:**
+```bash
+vuer --cert cert.pem --key key.pem --port 8012
+```
+
+**Generate Certificate:**
+Follow Let's Encrypt's localhost certificate guide for implementation details.
+
+## Complete Example with ngrok
+
+```python
+from vuer import Vuer
+from vuer.schemas import Scene, Urdf
+
+app = Vuer()
+
+@app.spawn
+async def main(session):
+    # Use the ngrok HTTPS domain for static files
+    session.set @ Scene(
+        Urdf(
+            src='https://xxxx.ngrok.io/static/urdf/robot.urdf',
+            position=[0, 0, 0],
+            key="robot",
+        ),
+    )
+
+    while True:
+        await asyncio.sleep(1.0)
+
+app.run()
+```
+
+Then access your app at:
+```
+https://vuer.ai?ws=wss://xxxx.ngrok.io
+```
+
+## Troubleshooting
+
+### WebSocket Connection Fails
+- Ensure you're using `wss://` (not `ws://`)
+- Verify the ngrok tunnel is running
+- Check firewall settings
+
+### Static Files Not Loading
+- Confirm HTTPS domain is correct
+- Verify static files are being served
+- Check browser console for mixed content warnings
+
+## Source
+
+Documentation: https://docs.vuer.ai/en/latest/tutorials/basics/ssl_proxy_webxr.html