feat: offline mode and static GitHub Pages build

.env.example

@@ -5,7 +5,7 @@ WORLD=world
 PORT=3000
 
 # The secret the server uses to create/parse json web tokens
-# IMPORTANT: Change this to a random string of at least 16 characters in production!
+# Recommended: use a random string of at least 16 characters in production
 JWT_SECRET=CHANGE_ME_TO_A_RANDOM_SECRET
 
 # The code used to become admin in the world (type /admin <code> in chat)

.github/workflows/docker.yml

@@ -17,16 +17,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4.1.4
+        uses: actions/checkout@v6
       - name: Login to GitHub Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@v6
         with:
           images: ghcr.io/${{github.repository}}
           tags: |
@@ -36,11 +36,11 @@ jobs:
             type=ref,event=pr
             type=sha,format=long
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@v4
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
       - name: Build and push
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@v7
         with:
           platforms: linux/amd64,linux/arm64
           push: true

.github/workflows/static-deploy.yml

@@ -0,0 +1,37 @@
+name: Deploy Static Build to GitHub Pages
+
+on:
+  push:
+    branches:
+      - dev
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+
+      - run: npm run static:build
+        env:
+          PUBLIC_WS_URL: ''  # Optional: set to wss://your-server.com/ws for a default server
+
+      - uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: build/static
+          publish_branch: gh-pages

README.md

@@ -100,6 +100,12 @@ npm run build
 npm start
 ```
 
+## 🚢 Deployment
+
+Build and run a production server with `npm run build && npm start`. Set `JWT_SECRET`, `ADMIN_CODE`, and `PUBLIC_WS_URL` in your `.env` before starting. A reverse proxy (nginx/Caddy) forwarding WebSocket upgrades to port 3000 is recommended for public deployments.
+
+See **[docs/deployment.md](docs/deployment.md)** for full setup instructions, Docker usage, and how to connect the GitHub Pages static preview to your server.
+
 ## 🖊️ Contributing
 
 Contributions are welcome! Please check out our [contributing guidelines](CONTRIBUTING.md) and [code of conduct](CODE_OF_CONDUCT.md) before getting started.

docs/deployment.md

@@ -0,0 +1,93 @@
+# Deployment
+
+## Self-hosting a server
+
+### 1. Configure environment
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and set at minimum:
+
+| Variable | Description |
+|---|---|
+| `JWT_SECRET` | Secret key for signing auth tokens (16+ chars recommended) |
+| `ADMIN_CODE` | Password for admin operations (backup, restore) |
+| `PORT` | HTTP port (default: `3000`) |
+| `PUBLIC_WS_URL` | Public WebSocket URL, e.g. `wss://your-server.com/ws` |
+| `PUBLIC_API_URL` | Public API URL, e.g. `https://your-server.com` |
+| `ASSETS_BASE_URL` | Base URL for serving uploaded assets |
+| `CORS_ORIGIN` | Allowed CORS origin (default: `*`) |
+
+### 2. Build and start
+
+```bash
+npm run build
+npm start
+```
+
+The server listens on `PORT` (default 3000). Visit `http://localhost:3000` to confirm it's running.
+
+### Docker
+
+```bash
+docker run -d \
+  --name hyperfy \
+  -p 3000:3000 \
+  -v $(pwd)/world:/app/world \
+  --env-file .env \
+  ghcr.io/hyperfy-xyz/hyperfy:latest
+```
+
+See [DOCKER.md](../DOCKER.md) for full details.
+
+### Reverse proxy (nginx / Caddy)
+
+Hyperfy uses WebSockets, so your proxy must forward upgrade headers.
+
+**nginx snippet:**
+```nginx
+location / {
+    proxy_pass http://localhost:3000;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header Host $host;
+}
+```
+
+**Caddyfile snippet:**
+```
+your-server.com {
+    reverse_proxy localhost:3000
+}
+```
+
+---
+
+## Connecting the GitHub Pages preview to a server
+
+The static build deployed to GitHub Pages boots in **offline mode** by default (no server required). There are two ways to point it at a real server.
+
+### Option 1 — Bake in a default server URL
+
+Edit `.github/workflows/static-deploy.yml` and add an `env` block to the build step:
+
+```yaml
+- run: npm run static:build
+  env:
+    PUBLIC_WS_URL: ''  # wss://your-server.com/ws
+```
+
+Replace the empty string with your WebSocket URL, push to `dev`, and the next deploy will bake it in. Setting it back to `''` (or removing the line) returns to offline mode.
+
+### Option 2 — Per-link override
+
+Share URLs with a `?connect=` query parameter:
+
+```
+https://your-org.github.io/hyperfy/?connect=wss://your-server.com/ws
+```
+
+This works without any build changes — visitors are connected to your server for that session only.