underpost

underpost

Base template for pwa/api-rest projects.

Underpost Platform

Underpost is an platform for application delivery, from infrastructure to runtime. The underpost npm package is its CLI toolchain surface.

The project covers:

• Bare metal provisioning on Rocky Linux 9.
• Kubernetes / K3s / kubeadm / LXD workflows for production, edge, and isolated workloads.
• GitHub OSS repository flow — clone, pull, push, commit, release, and CI integrations as first-class CLI subcommands.
• CI/CD orchestration — GitHub Actions integrations, container builds, multi-environment deployments.
• Static build + PWA delivery — every deploy ships as an installable Progressive Web App with Workbox-based offline support.
• Cloudinary-backed static asset flow for image/asset delivery.
• ERP/CRM-style PWA base applications as the default workload.
• Cyberia — a dedicated MMO extension built on top of the platform, with its own content backend (engine-cyberia), authoritative simulation runtime (cyberia-server), and presentation runtime (cyberia-client).

See Detailed platform doc.

Architectural roles (Cyberia stack)

When the platform is hosting the Cyberia MMO extension, three independent runtime processes participate. Their boundaries are non-overlapping.

Process	Role
engine-cyberia (Node.js)	Content authority: maps, object layers, atlas/asset metadata, world configuration, persistence, validation, gRPC + REST data services, editor backend, asset distribution.
cyberia-server (Go)	Authoritative simulation runtime: tick advancement, AOI replication, input command processing, snapshot generation.
cyberia-client (C → WebAssembly)	Presentation runtime: rendering, UI, input capture, prediction, reconciliation, interpolation, client-side presentation defaults.

The ecosystem is playable only when all three are running and healthy. Each service is supervised independently and owns its own monitor/reconnector. If any one is unhealthy, the game enters standby and resumes automatically once all three are healthy again.

See detailed Cyberia architecture.

Create a new project

npm install -g underpost

underpost new app-name

After template installation, the server will be running on http://localhost:4001

Usage

cd app-name

Build client bundle

npm run build

Run dev client server

npm run dev

See Docs.

Underpost CLI

underpost ci/cd cli v4.0.0

Usage: underpost [options] [command]

Global options

Option	Description
-V, --version	output the version number
--profile <profile>	Execution profile. One of: LIVE_CLUSTER, HERMETIC_BUILD, OFFLINE_DRY_RUN. LIVE_CLUSTER Full access: cluster and host mutation permitted. HERMETIC_BUILD Build outputs only: no cluster, host or network side effects. OFFLINE_DRY_RUN Nothing executes; every command is reported as intent.
-h, --help	display help for command

Commands

Command	Description
new	Initializes a new Underpost project, service, or configuration.
site	Provisions sites in the configuration of a deployment: clients, host/path routes, and the existing APIs and components they use. Each operation prints its change plan and applies it as one change set.
client	Builds client assets, single replicas, and/or syncs environment ports.
start	Initiates application servers, build pipelines, or other defined services based on the deployment ID.
clone	Clones a specified GitHub repository into the current directory.
pull	Pulls the latest changes from a specified GitHub repository.
cmt	Manages commits to a GitHub repository, supporting various commit types and options.
push	Pushes committed changes from a local repository to a remote GitHub repository.
static	Manages static build of page, bundles, and documentation with comprehensive customization options.
root	Displays the root path of the npm installation.
ip	Displays the current public machine IP addresses.
cluster	Manages Kubernetes clusters, defaulting to Kind cluster initialization.
deploy	Manages application deployments, defaulting to deploying development pods.
secret	Workload secret store: SOPS/Age encrypted credentials projected as Kubernetes Secrets.
host	Host configuration: the node-level operational environment shared by the cluster.
app	Application environment: one deployment's runtime configuration.
state	Runtime state: live container execution state, health and metrics, exported off-cluster.
image	Manages Docker images, including building, saving, and loading into Kubernetes clusters.
install	Quickly imports Underpost npm dependencies by copying them.
db	Manages MariaDB and MongoDB databases: sealed backups in the object store, restores, verification and restore drills, retention, and statistics.
metadata	Manages cluster metadata operations, including import and export.
cron	Manages cron jobs: execute jobs directly or generate and apply K8s CronJob manifests.
fs	Uploads, pulls, or deletes Cloudinary assets and synchronizes the selected storage manifest.
monitor	Manages health server monitoring, the cluster observability stack, and host dashboards.
event	Dispatches operational events and provisions the monitoring rules that trigger them.
ssh	Manages cluster scoped SSH credentials and sessions for remote access to cluster nodes or services. Users are registered in engine-private/deploy/conf.users.json and keys are stored in engine-private/deploy/users/.
wireguard	Manages the WireGuard L3 hub-and-spoke transport and the HAProxy edge gateway in front of it.
haproxy	Manages the HAProxy edge gateway over the WireGuard transport (same subsystem as underpost wireguard).
vultr	Meters the edge VPS bandwidth against its Vultr plan quota and blocks egress before overage accrues.
run	Runs specified scripts using various runners.
test	Runs the test projects locally, inside deployment pods, or as a cluster Job with Allure reporting.
docker-compose	General-purpose Docker Compose development pipeline (mirrors the Kubernetes dev stack).
lxd	Manages LXD virtual machines as K3s nodes (control plane or workers).
baremetal	Manages baremetal server operations, including installation, database setup, commissioning, and user management.
package	Generates the package manifests a deploy id owns, from the engine manifest and the deploy's product catalog, and installs the dependencies that catalog pins.
socketsecurity	Security audit through the Socket.dev free plan: dependency security (advisories, supply chain alerts, free security patches in .socket/manifest.json) and source code risk (alerts on this project's own code).
graphify	Builds the code graph of this checkout with the pinned Graphify release, code only. It commits GRAPH_REPORT.md and its stamp in docs/graphify-out.
release	Release orchestrator for building new versions and deploying releases of the Underpost CLI.
source-release	Source channels, the Release Job and the release store.