Changelog v3.2.12

2026-05-31

docs

Refactor Underpost Platform documentation for clarity and structure (e554d3d69)

engine-cyberia

Refactor README and CLI command descriptions for clarity and consistency (b322c77f1)

server-conf

Refactor awaitDeployMonitor parameters inverse arg functionality and fianl deployment event handle (c34661ad0)

server-start

Remove error throw on unexpected deployment exit for improved error handling (e6554e09c)

New release v:3.2.11 (2026-05-31)

deploy

Fix deployment error handling: ensure global secret cleanup only occurs if container status is not 'error' (83ef9d8cf)
Add Underpost integration for container status error handling in database and Valkey services (3bbcdcf49)

bin-build

Prevent OnError workflow break on empty commit (494fc93ab)

cli-run

Add k3s-template-env case logic: clean up existing dd-default config and update .env.example (90a910630)
Add 'remove' option for resource teardown and improve MongoDB handling (11c09deb6)
Enhance clean method: execute shared-dir script in development mode (317806d8f)
Rename setup-shared-dir method to shared-dir and remove reload-shared-dir method for clarity and simplification (7985353cb)
Add exit process on error instead of returning null (567008c3d)

client-core

Add modal event handling: introduce ModalEventType, ModalListenerChannels, and createModalEvents for improved modal interactions (d31bf3b01)
Fix focus handling in Auth and Modal components: prevent focus on search box when skipFocus is true (95a42637c)

bin-deploy

Add vm-cluster-env case logic (d55b6120d)

release

Refactor release build process: replace file.js with build.template.js, update package.json script, and enhance repository methods for GitHub directory fetching (05c0e1d85)

baremetal

Refactor NFS configuration: update NFSv3 ports and streamline NFS root mount options (217c736ea)
Enhance iPXE build process: track embedded script changes to ensure rebuilds when necessary (4d9d572bf)
Refactor NFS configuration and enhance GRUB module installation for baremetal provisioning (c94dd434b)

lxd

Enhance LXD management: add support for MAAS project handling and improve command execution consistency (0910817c5)
Refactor: reorganize LXD Management documentation for clarity and safety (5cc554cfe)

cluster

Refactor deployment and monitoring to centralize /etc/hosts management (a10ad7da6)
Add MongoDB manifests including headless service, stateful set, and storage class (8fd1d8172)

repository

Enhance git command execution in file storage and repository modules for improved error handling and logging (bb008852d)

engine

Update VSCode configuration: add bash-beautify extension and enhance settings for shellscript and json (e0e3c5249)

db

Refactor MongoDB data directory cleanup logic in Kind nodes to use docker exec for reliability (87d66f223)
Refactor MongoDB cleanup logic to avoid stale bind mounts and ensure proper directory structure (c07098e8c)

cli-secrets

Add secret management command to deployment workflows (796fddb46)

cli-deploy

Fix ready monitor method to wait container runtime complete setup (c89231a06)

github-actions

Prevent dependabot gitleaks run (16c2a0c1d)

New release v:3.2.10 (2026-05-26)

cli-run

Add group property and shared directory setup methods to UnderpostRun (6cc121c4a)

cli-release

Add bumpp configuration and integrate version bumping into release process (e5eb50d70)

engine-cyberia

Refactor CI workflows for cyberia-client and cyberia-server, removing outdated comments and improving clarity. Update Dockerfile to ensure clean builds by adding a clean step before compilation. (e74918e81)
Refactor CI workflows and Dockerfiles for cyberia-client and cyberia-server (0dfda92fd)
Refactor package.json metadata for Cyberia CLI and Underpost Platform, updating descriptions and keywords for improved clarity and relevance. (893a371ac)
Enhance Dockerfiles and CLI: align underpost versioning, add dev configurations, and improve manifest build options (4f9c96df6)
Refactor presentation handling: remove legacy fields, update documentation, and streamline client hints integration (e79315e6e)
Refactor Cyberia defaults management (2454ad54c)
Add cyberia hints model and refactor docs (14fc8a633)
Update build process to include README.md and update white paper version (77099e88f)

client

Chore landing icons (ed1bc3fee)

github-actions

Add condition to skip jobs for dependabot in Coverall CI workflow (db35270a6)
Enhance underpost test execution and improve error handling (d046dcee2)
Update CI workflows to specify repository paths for cyberia-client and cyberia-server; adjust Dockerfile to copy from the correct directory (9bef93774)

cli-deploy

Add imagePullPolicy option to deployment commands and documentation (d1ebe5d71)
Enhance deployment monitoring: improve pod readiness checks, add container-status validation, and refine logging for deployment progress (3cb67b64b)

gitub-actions

Enhance CI workflow and Dockerfiles to include SSR dashboard setup and dependencies (6e8db980f)

client-core

Enhance file handling logic and improve UI interactions in PanelForm and Auth components (f4e146195)
Enhance offline and maintenance fallback handling: implement inline HTML responses, improve caching logic, and ensure user-friendly error pages (1802b40ca)
Enhance service worker fallback handling: add inline HTML responses for offline and maintenance states, improve caching logic, and refine navigation fetch strategy (bc2a1a0ca)
Add SSR views for server metrics, maintenance, and offline handling (81ca21084)

dependencies

Update dependencies and improve branch deletion error handling (bcbf1a5e3)
Update dependencies: bump body-parser to 1.20.5, express to 4.22.2, and qs to 6.15.2 (3d5da7d28)

ssr-cyberia

Refactor ssr/views/CyberiaServerMetrics.js (7184a738d)

cli

Enhance error handling: silence errors during git commit and process termination (7583c4f12)

cluster

Add targeted reset option for MongoDB components without full cluster restart (8c293e11d)
Enhance UnderpostCluster: add natSetup method for NAT and iptables configuration, improve cluster deletion logic, and update options parameter for config method (b90d7dba7)

ipfs

Fix IPFS deployment: streamline UDP buffer sysctl application for Kind nodes (2b08cbc6d)

db

Refactor MongoDB bootstrap logic: enhance admin authentication check and streamline initialization script execution (866e56c63)
Refactor MongoDB primary pod detection and bootstrap logic (609f5e89b)
Refactor MongoDB manifests and initialization: update PersistentVolume configurations, enhance StatefulSet security, and improve MongoDB cluster bootstrap logic (ed89c3850)
Refactor DataBaseProviderService: change #instance to static and update instance getter for compatibility (360d2c856)
Refactor replace DataBaseProvider with DataBaseProviderService across services and routers (614e47314)
Enhance MongoDB configuration and management: update stateful set parameters, improve secret handling, and implement replica set initialization logic (1fb895669)

ws

Refactor WebSocket management context: replace wsManagementId with hostKeyContext across IoInterface and related channels (b82c80fce)

deploy

Enhance deployment error handling: update expected container status, throw errors for pod status issues, and manage container status in shell execution (d170f36cc)

lxd

Enhance LXD management: add safe teardown for VMs, improve engine source replication, and update documentation (e9b3a68c9)

api

Enhance ObjectLayerService command execution with error context (4253b2437)

docs

Clean docs (465507082)
Update README.md for clarity and improved documentation links (4021b6fcb)
Add jsdelivr badge (d2a6f2931)
Update file paths and command syntax in architecture and client/server documentation (f51891d44)

settings

Update default formatters for JSON and TypeScript files (e2c20b6f8)

dependabot

Update dependency patterns in dependabot.yml for improved package management (60e8605c3)

cli-cyberia

Refactor CyberiaDialogue handling to use codes instead of itemIds for improved dialogue management (273fed2e4)

runtime-cyberia

Refactor Dockerfiles for cyberia-client and cyberia-server to streamline package installations and improve build processes (0312126c7)

bin-vs

Fix correct typo in clean case to remove vsConfigRootPath (0251c45a3)

CYBERIA

Network Object Layers

Stackable Rendering Layers as a Unified Tokenized Reality

Cyberia is an MMORPG extension built on the Underpost Platform. The platform owns the toolchain, deployment surface, PWA delivery, and base infrastructure. Cyberia adds a three-service MMO runtime: `engine-cyberia`, `cyberia-server`, and `cyberia-client`.

engine-cyberia is the sidecar-backed data layer: a Node.js sidecar that owns content,
validation, persistence, the gRPC/REST data services, and asset metadata. It backs the authoritative
Go server and the WASM client with data — it does not run the simulation or the presentation.

Ecosystem at a glance

                         ┌───────────────────────────────────────────────┐
                         │              UNDERPOST PLATFORM                 │
                         │  toolchain · deploy · PWA build · static        │
                         │  delivery · cluster/image/db · monitoring       │
                         │                                                 │
                         │   underpost CLI  ──▶  builds & deploys all      │
                         └───────────────────────────────────────────────┘
                                            │  hosts / delivers
                                            ▼
   ╔═══════════════════════════════ CYBERIA MMO ══════════════════════════════════╗
   ║                                                                               ║
   ║   ┌──────────────────┐   gRPC    ┌──────────────────┐   WebSocket            ║
   ║   │  engine-cyberia  │ ────────▶ │  cyberia-server  │ ───────────┐           ║
   ║   │     (Node.js)    │           │       (Go)       │            │           ║
   ║   │                  │           │                  │            ▼           ║
   ║   │ content          │           │ authoritative    │   ┌──────────────────┐ ║
   ║   │ validation       │           │ simulation       │   │  cyberia-client  │ ║
   ║   │ persistence      │           │ world tick       │   │    (C / WASM)    │ ║
   ║   │ gRPC/REST data   │           │ AOI replication  │   │                  │ ║
   ║   │ asset metadata   │           │                  │   │ rendering        │ ║
   ║   └──────────────────┘           └──────────────────┘   │ input            │ ║
   ║            │                                             │ prediction       │ ║
   ║            └──────────────── REST (content/assets) ─────▶│ presentation     │ ║
   ║                                                          └──────────────────┘ ║
   ╚═══════════════════════════════════════════════════════════════════════════════╝

   One source of truth per concern:
     content & world config ── engine-cyberia
     real-time world state  ── cyberia-server
     presentation & input   ── cyberia-client

1. Toolchain and base infrastructure

Underpost Platform is the operational backbone and the source of truth for deploy IDs, runtime
selection, host/path layout, generated client assets, and environment resolution.

Area	What it owns
Toolchain	`underpost` CLI, build, deploy, release, metadata, secrets, environment selection
Infrastructure	bare metal, LXD, Kubernetes, K3s, kubeadm, images, SSH, runners
Data operations	MongoDB, MariaDB where needed, backups, cron, monitoring
Delivery	static build, SSR views, PWA packaging, service worker generation, host/path routing

underpost is the shared control surface for everything infrastructural. Cyberia-specific work belongs
in the cyberia CLI, never in parallel platform commands. When a concern already exists in underpost,
reuse it instead of forking a Cyberia variant.

2. PWA workflow

Every deployed client ships as a static application shell with PWA support. The pipeline has exactly two
inputs:

the deploy ssr configuration in conf.dd-*.js (or conf.ssr.json)
the service worker source in src/client/sw/core.sw.js

Everything else — index.html pages, sw.js, the precache list — is generated during the client
build. Treat them as outputs only; never hand-edit them.

Runtime service-worker behavior:

Request	Strategy
static assets	stale-while-revalidate
API `GET`	network-first + short cache
API mutations	network-only + background replay
navigation	network-first + fallback shells

Fallback selection: offline network → offline fallback view; origin/server failure → maintenance
fallback view. Only fallback-marked views are guaranteed precached.

3. Cyberia MMO extension

Responsibility split

Service	Owns	Must not own
`engine-cyberia`	content, validation, persistence, gRPC/REST data services, asset metadata	authoritative simulation, render policy
`cyberia-server`	authoritative simulation, world tick, gameplay mutation, AOI replication	content authority, presentation metadata
`cyberia-client`	rendering, input, prediction, interpolation, presentation	authoritative world state, gameplay authority

Two boundaries are non-negotiable:

Do not move authoritative logic into the client.
Do not move content-authority logic into the Go runtime.

Data flow

engine-cyberia ──gRPC──▶ cyberia-server ──WebSocket──▶ cyberia-client
engine-cyberia ──REST──────────────────────────────▶ cyberia-client

`engine-cyberia` as the sidecar-backed data layer

engine-cyberia is the only Cyberia service that owns content-backed data and asset metadata.

Boot-time world configuration flows from engine-cyberia to cyberia-server over gRPC GetFullInstance.
Client-facing assets, object layers, dialogues, and presentation hints flow from engine-cyberia to cyberia-client over REST.
Simulation never migrates into the sidecar, and presentation policy never migrates out of the client.

Runtime / health model

Three supervised processes run in parallel, each with its own monitor and reconnect loop. Gameplay is live only when all three are healthy at once.

        ┌──────────────────────────────────────────────────────────────┐
        │                    SUPERVISION (parallel)                      │
        │                                                                │
        │   engine-cyberia        cyberia-server        cyberia-client   │
        │   ┌────────────┐        ┌────────────┐        ┌────────────┐   │
        │   │  monitor   │        │  monitor   │        │  monitor   │   │
        │   │ +reconnect │        │ +reconnect │        │ +reconnect │   │
        │   └─────┬──────┘        └─────┬──────┘        └─────┬──────┘   │
        │         │                     │                     │          │
        │         └──────────┬──────────┴──────────┬──────────┘          │
        │                    ▼                     ▼                     │
        │            all three up & connected?                          │
        └────────────────────────────┬─────────────────────────────────┘
                                      │
                ┌─────────────────────┼─────────────────────┐
                ▼                     ▼                     ▼
          ┌───────────┐        ┌───────────┐         ┌───────────┐
          │  HEALTHY  │        │ DEGRADED  │         │  STANDBY  │
          │ all 3 up  │        │ ≥1 service│         │ gameplay  │
          │ gameplay  │        │ reconnect-│         │ paused    │
          │ live      │        │ ing / down│         │ until all │
          │           │        │           │         │ 3 healthy │
          └───────────┘        └───────────┘         └───────────┘

State	Meaning
`healthy`	all three Cyberia services are up and connected
`degraded`	at least one service is reconnecting or unavailable
`standby`	gameplay is paused because the full three-service set is not healthy

User commands

Use underpost for platform, infrastructure, build, and deploy. Use cyberia for MMO content and
extension workflows. Both share the same helpers — never duplicate config, env, or path logic.

Platform (underpost)

# Bootstrap a new app (local app serves on http://localhost:4001)
underpost new app-name

# Build the client bundle / static + PWA output
underpost client
npm run build            # node bin client

# Deploy and operate
underpost deploy <deploy-id>
underpost monitor

Cyberia (cyberia) — `bin/cyberia.js`

Group	Command	Purpose
`ol`	`cyberia ol [item-id]`	ObjectLayer import, procedural generation, atlas/sprite
`instance`	`cyberia instance [instance-code]`	export / import / drop a Cyberia instance and its data
`client-hints`	`cyberia client-hints [instance-code]`	per-instance presentation hints (palette, camera, icons)
`chain`	`cyberia chain <sub>`	Hyperledger Besu + ERC-1155 ObjectLayerToken lifecycle
`run-workflow`	`cyberia run-workflow <name>`	named maintenance/build scripts from `scripts/`

Common examples:

# Object layer content
cyberia ol hatchet,sword --import                 # import specific items
cyberia ol --import-types skin,floors             # batch import by type (or: all)
cyberia ol floor-desert --generate --seed fx-42   # procedural generation
cyberia ol hatchet --to-atlas-sprite-sheet        # build atlas sprite sheet
cyberia ol --drop --client-public                 # drop data + static asset folders

# Instance data
cyberia instance FOREST --export ./backup
cyberia instance FOREST --import ./backup
cyberia instance FOREST --drop

# Presentation hints
cyberia client-hints cyberia-main --seed-defaults

# Chain / token lifecycle
cyberia chain deploy --chain-id 777771
cyberia chain status
cyberia chain register / mint / transfer / burn / pause / unpause

# Named workflows
cyberia run-workflow import-default-items
cyberia run-workflow seed-skill-config --instance-code default
cyberia run-workflow seed-dialogues
cyberia run-workflow build-manifest
cyberia run-workflow build-server-dashboard

Run the MMO services

# engine-cyberia (Node.js data/content services)
npm start                                          # node src/server

# cyberia-server (Go authoritative simulation)
cd cyberia-server && go run main.go                # dev
cd cyberia-server && go build -o cyberia-server . && ./cyberia-server

# cyberia-client (C / WASM presentation)
cd cyberia-client && make -f Web.mk clean && make -f Web.mk web
cd cyberia-client && make -f Web.mk serve-development     # serves on :8082

v3.2.12

Changelog v3.2.12

2026-05-31

docs

engine-cyberia

server-conf

server-start

New release v:3.2.11 (2026-05-31)

deploy

bin-build

cli-run

client-core

bin-deploy

release

baremetal

lxd

cluster

repository

engine

db

cli-secrets

cli-deploy

github-actions

New release v:3.2.10 (2026-05-26)

cli-run

cli-release

engine-cyberia

client

github-actions

cli-deploy

gitub-actions

client-core

dependencies

ssr-cyberia

cli

cluster

ipfs

db

ws

deploy

lxd

api

docs

settings

dependabot

cli-cyberia

runtime-cyberia

bin-vs

CYBERIA

Ecosystem at a glance

1. Toolchain and base infrastructure

2. PWA workflow

3. Cyberia MMO extension

Responsibility split

Data flow

engine-cyberia as the sidecar-backed data layer

Runtime / health model

User commands

Platform (underpost)

Cyberia (cyberia) — bin/cyberia.js

Run the MMO services

Uh oh!

`engine-cyberia` as the sidecar-backed data layer

Cyberia (cyberia) — `bin/cyberia.js`