Gnosis Server + Laravel Portal Setup

Documentation Freshness (2026-04-19)

• This page has been reviewed against the current terminal/server build and the latest portal documentation surfaces.
• For exact live catalogs and tuning values, use the source-driven portal compendiums:
  • /bestiary
  • /spell-omnibus
  • /technique-omnibus
  • /item-omnibus
  • /recipe-omnibus
• In-game references are available through the W wiki menu (including generated spell/component compendiums).
• World/floor map reference is in-game via P; the website map page is intentionally hidden.
• Multiplayer host/deployment details live in docs/multiplayer_server_wiki.md and docs/server_portal_setup.md.

Current Build Delta (2026-04-19)

• Deep floors now have a depth-scaled chance to spawn Lizard Kingdom Gates (FeatureLizardKingdomGate).
• Using a Lizard Kingdom Gate enters Lizard Kingdom side sites (SiteLizardKingdom) with lizard society-biased populations.
• Lizard Kingdom floors use dedicated cave themes (Outer Warrens -> Royal Sinkhalls) and integrate with map/examine/senses/clairvoyance text.
• This update is live in terminal mode and server mode; hosted clients inherit the behavior from the game build.

1. Start Shared Postgres

The portal compose stack expects the shared postgres_db container from /workspace/container-pgsql/ on the dev-net network.

cd /workspace/container-pgsql
docker compose up -d

This stack includes a dedicated gnosis_web database/user for the Laravel portal.

2. Build or Run the Go Server

cd /workspace/gnosis
go build ./...

3. Start gnosisd (SSH + Websocket)

Set matching secrets first:

export GNOSIS_PROVISION_SECRET='replace-this'
export GNOSIS_WS_SECRET='replace-this'

gnosisd now refuses to start with placeholder defaults. For throwaway local testing only, you can override with GNOSIS_SERVER_ALLOW_INSECURE_DEFAULTS=1.

Run:

go run ./cmd/gnosisd \
  -ssh-addr :2222 \
  -http-addr :8080 \
  -world-config /path/to/world-config.json

Dedicated host note: when -world-config/GNOSIS_SERVER_WORLD_CONFIG is set, sessions are locked to that configured world. If the file is missing or invalid, clients cannot connect until fixed.

If you are using the Steam bundle instead of a source checkout, the equivalent host wrapper is ./dist/steam/linux-amd64/host-server.sh.

If you want a standalone Dockerized host without Laravel, use:

docker compose -f docker-compose.server.yml up -d --build

That publishes 2222 (SSH) and 8080 (HTTP/WebSocket) on all interfaces by default and enables GNOSIS_SERVER_SSH_KEY_IDENTITY=1 for key-bound SSH identities.

The Docker host expects:

• /var/lib/gnosis-server/world-config.json

If missing, /healthz reports not ready and player sessions are blocked. On first start, the entrypoint copies:

• /var/lib/gnosis-server/world-config.json.example

from repository template docker/world-config.example.json.

Operational rule:

• changing settings in world config takes effect after server restart
• changing seed requires archiving/deleting old world save data before restart

If you want the Laravel portal stack, use webapp/docker-compose.yml. It builds a dedicated gnosisd image, publishes SSH on 127.0.0.1:2222, and publishes the browser websocket host on 127.0.0.1:9005.

Compendium note: the portal reads internal/game source metadata to populate /spell-omnibus, /technique-omnibus, /item-omnibus, and /recipe-omnibus, and also exposes a unified /audit-omnibus dump page. The compose file mounts this path at /app/internal/game and sets GNOSIS_GAME_SOURCE_DIR=/app/internal/game by default.
Fallback note: if live parsing is unavailable, the portal can serve a full snapshot from GNOSIS_CATALOG_SNAPSHOT_PATH (default data/wiki_catalog_snapshot.json), generated by php artisan gnosis:export-catalog-snapshot --pretty.

4. Start Laravel Portal

cd /workspace/gnosis/webapp
test -f .env || cp .env.example .env
docker compose up --build

Runtime behavior:

• APP_RUNTIME=serve runs php artisan serve (local default)
• APP_RUNTIME=octane runs Laravel Octane with RoadRunner
• if APP_RUNTIME is unset, startup defaults to octane when APP_ENV=production, otherwise serve

Set these values in .env:

• APP_URL
• WEB_PORT=9004
• SERVER_HTTP_PORT=9005
• SERVER_SSH_PORT=2222
• LARAVEL_PORT=8000
• APP_RUNTIME (serve for local, octane for production)
• OCTANE_WORKERS, OCTANE_TASK_WORKERS, OCTANE_MAX_REQUESTS (when using octane)
• GNOSIS_SERVER_URL=http://gnosisd:8080 for compose, or http://127.0.0.1:8080 for a direct process
• GNOSIS_WS_URL=ws://127.0.0.1:9005/ws for local compose, or wss://gnosis.cordine.site/ws for production
• GNOSIS_SSH_HOST
• GNOSIS_SSH_PORT
• GNOSIS_PROVISION_SECRET
• GNOSIS_WS_SECRET
• GNOSIS_DEMO_MODE=1 to hide tester/world/setup/backup/quit in the game title menu (set 0 to restore full menu)
• GNOSIS_PLAY_VISION_STREAM_ENABLED=0 by default (set 1 only if you explicitly want /play vision SSE)
• GNOSIS_GAME_SOURCE_DIR=/app/internal/game (or another absolute path to internal/game)
• GNOSIS_CATALOG_SNAPSHOT_PATH=/app/data/wiki_catalog_snapshot.json (fallback full-catalog snapshot)
• GNOSIS_DISABLE_VISION_STREAM_UNDER_OCTANE=1 to auto-disable /play vision SSE when APP_RUNTIME=octane
• GNOSIS_DOCS_DIR=/app/docs if you are not using the default docs mount

If you are iterating on the portal without a live Go server, set GNOSIS_SKIP_PROVISION=1 in webapp/.env so registration does not call /api/provision.

5. Account Flow

1. Register a portal account on the published portal URL.
   • For the Docker compose stack, use http://127.0.0.1:9004/register.
   • For a manual run, use your APP_URL host.
2. Registration provisions an SSH account in gnosisd.
3. Open Profile and upload a public SSH key if you want passwordless login.
   • Leave the field blank to remove the key.
   • The portal forwards the normalized key to gnosisd.
4. Use dashboard for:
   • SSH config snippet for passwordless login
   • browser play (/play)
   • live server snapshot, featured characters, and major events
   • wiki browsing/searching
   • Steam-facing support/legal pages

6. Production Host

The production public host for this deployment is gnosis.cordine.site.

Use webapp/.env.production.example as the base .env for that deployment.

Required production values:

• APP_ENV=production
• APP_URL=https://gnosis.cordine.site
• APP_RUNTIME=octane
• OCTANE_SERVER=roadrunner
• OCTANE_HTTPS=true
• GNOSIS_WS_URL=wss://gnosis.cordine.site/ws
• GNOSIS_SSH_HOST=gnosis.cordine.site
• SESSION_SECURE_COOKIE=true

The dashboard SSH snippet should point at gnosis.cordine.site and the user's uploaded key must exist in the profile page before passwordless login will succeed.

7. Observer Turn Lock

• Enabled automatically in gnosisd by GNOSIS_TURN_SYNC.
• On each resolved turn, players publish observer state.
• If two players mutually see each other, turns block until each observer resolves.
• During block, UI shows waiting status.