Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tuturuuu.com/llms.txt

Use this file to discover all available pages before exploring further.

Hive realtime lives in apps/hive-realtime. It is a Bun WebSocket service used only by Hive; do not replace it with Supabase Realtime.

​
Required Environment

  • HIVE_REALTIME_TOKEN_SECRET: preferred shared HMAC secret used by apps/web to mint short-lived join tokens and by apps/hive-realtime to validate them. If this is not set, both services fall back to the existing platform Supabase service secret from the shared apps/web environment. This keeps Hive deployable with the same Supabase setup as apps/web, while still allowing operators to rotate Hive realtime signing independently later.
  • HIVE_REALTIME_URL: internal server URL used by apps/web and apps/hive when they need the service-side endpoint.
  • NEXT_PUBLIC_HIVE_REALTIME_URL: browser-facing WebSocket URL, normally wss://hive.tuturuuu.com/realtime in production.
  • Supabase credentials already used by apps/web, especially NEXT_PUBLIC_SUPABASE_URL with SUPABASE_SECRET_KEY. SUPABASE_SERVER_URL may still override the server-side URL when the deployment needs a Docker-internal Supabase origin.
apps/hive shares the same Supabase setup as apps/web. Docker runtime env comes from .env.local with the same apps/web/.env.local fallback, and the production Hive image receives the web_env BuildKit secret during next build so prerendered auth routes can resolve NEXT_PUBLIC_SUPABASE_URL and related platform Supabase variables.

​
Local production-style servers (Turbo)

From the repo root, Turbo runs workspace dependency builds first, then starts each process (see turbo.json tasks @tuturuuu/hive#serve:hive and @tuturuuu/hive-realtime#serve:hive-realtime):
  • bun serve:hive — production Next server for Hive on port 7814 (requires a prior next build output; Turbo schedules build before serve:hive).
  • bun serve:hive-realtime — Bun WebSocket server (default port 7815 via PORT).

​
Blue/Green Deployment

docker-compose.web.prod.yml runs hive-blue, hive-green, and hive-realtime with the same production Supabase environment as apps/web. scripts/docker-web/blue-green.js promotes Hive with the same active color as web and waits for the target Hive color before proxy handoff. The generated nginx config routes:
  • hive.tuturuuu.com/ to the active hive-{color} satellite app on port 7814.
  • hive.tuturuuu.com/realtime to hive-realtime on port 7815.
The production proxy also listens on host port 7814, so a Cloudflare tunnel mapping hive.tuturuuu.com to localhost:7814 still goes through the blue/green proxy instead of bypassing it to a stale single Hive container. scripts/watch-blue-green-deploy.js watches the Hive Dockerfiles, package manifests, realtime source files, and docker-compose.web.prod.yml; changes to these files trigger the watcher container refresh path.

​
Protocol

Clients connect with a short-lived token from POST /api/v1/hive/servers/:serverId/realtime-token. Tokens include user ID, server ID, role, expiry, and event scopes. Accepted client messages are typed commands:
  • block.place
  • block.remove
  • object.place
  • object.remove
  • object.move
  • npc.move
  • npc.config
  • npc.decision
  • server.metadata
  • selection
  • presence.join
World events are persisted through the central apply_hive_world_event(...) RPC so stale revisions are rejected before broadcast. Revision conflicts are a normal editor sync condition, not an operational error. The web API checks the current revision before calling the RPC, and the RPC returns an empty result for last-moment conflicts instead of raising hive_revision_conflict; this prevents stale editors from flooding Postgres logs and database usage. The Hive client also serializes world-edit saves and applies a short cooldown after a conflict. If a user edits against an old revision, Hive reloads the latest snapshot and waits for the next explicit edit instead of immediately retrying a rebased mutation loop. When an edit is accepted by the central API first, the Hive app emits world.event.applied to the WebSocket service. The realtime service validates that the token server ID matches the event server ID, then broadcasts the event and full accepted world snapshot to that server room. This keeps other clients from resurrecting deleted blocks by refetching a stale snapshot before the accepted revision is visible.