wos-deploy 2.1.0__py3-none-any.whl

wos_deploy/__init__.py

@@ -0,0 +1,3 @@
+"""WOS Deployment Manager."""
+
+__version__ = "2.1.0"

wos_deploy/cli.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""
+WOS Deployment Manager - pip-installable CLI entry point.
+
+Thin wrapper that imports the deployment logic and patches the template
+directory to point at the bundled package data instead of the script's
+parent directory.
+"""
+
+import importlib.util
+import sys
+from importlib.resources import files as pkg_files
+from pathlib import Path
+
+
+def main():
+    # Resolve the bundled templates directory
+    templates_dir = Path(str(pkg_files("wos_deploy") / "templates"))
+
+    # Load wos-deploy.py as a proper module so @dataclass etc. work
+    module_name = "wos_deploy_impl"
+    spec = importlib.util.spec_from_file_location(
+        module_name,
+        templates_dir / "wos-deploy.py",
+    )
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = mod
+    spec.loader.exec_module(mod)
+
+    # Patch WOSDeployment so script_dir resolves to our bundled templates
+    _original_init = mod.WOSDeployment.__init__
+
+    def _patched_init(self):
+        _original_init(self)
+        self.script_dir = templates_dir
+
+    mod.WOSDeployment.__init__ = _patched_init
+
+    # Run
+    mod.main()
+
+
+if __name__ == "__main__":
+    main()

wos_deploy/templates/README.md

@@ -0,0 +1,252 @@
+# WOS Deployment
+
+Docker-based deployment tooling for WOS instances.
+
+## Requirements
+
+- Python 3.8+
+- Docker Engine with `docker compose`
+- Linux host on `x64` or `arm64`
+
+## Quick Start
+
+The command is `wos-deploy` (`wos` is kept as an alias; a deployment folder created by `setup-folder` from a source checkout also carries a `./wos` wrapper).
+
+Create an instance:
+
+```bash
+wos-deploy setup-folder ../wos-prod --env prod --port-offset 3
+cd ../wos-prod
+```
+
+Resolve topology and run initialization:
+
+```bash
+wos-deploy setup-private --wosgw <global-gateway-host>:<port>
+```
+
+`--wosgw` (or `WOSGW` in the environment) is required: there is no built-in gateway.
+
+or:
+
+```bash
+wos-deploy setup-global --enable_ctp --enable_secondary
+```
+
+Start services:
+
+```bash
+wos-deploy deploy
+```
+
+## CLI
+
+- `setup-folder <folder_name> [--template-dir PATH] [--env dev|prod] [--port-offset N]`
+- `setup-private [-r|--run] [--enable_ctp] [--enable_secondary] --wosgw HOST:PORT`
+- `setup-global [-r|--run] [--enable_ctp] [--enable_secondary]`
+- `setup-rfq [-r] [--render-only] [--registry R] --image-tag T [--enable_ctp] [--enable_secondary] [...]` (see below)
+- `--version`
+- `deploy [--skip-pull]`
+- `restart [service]`
+- `shutdown [service]`
+- `status [-j|--json]`
+- `logs [-f|--follow] [service]`
+- `shell [-u|--user USER] [--shell PATH] service`
+- `reset`
+- `config`
+
+## Flow
+
+`setup-folder` creates the instance directory, copies `templates/`, symlinks the deployment assets, and creates the base `volumes/` layout.
+
+The deployment uses:
+
+- `docker-compose.yml` for `wos-init` and `wos-primary`
+- `docker-compose.secondary.yml` for optional `wos-secondary`
+- `.config` as a small env-style state file written by `setup-folder`
+- `.env` as the runtime variable file consumed by compose and init/functions
+
+`setup-private` and `setup-global` now do the real initialization work:
+
+1. read `.config`
+2. show the resolved configuration and ask for confirmation unless `-r` is used
+3. resolve topology and write `.env`
+4. copy enabled `templates/<namespace>/*.yml` files into `volumes/data/init/<namespace>/`
+5. pull the required images
+6. generate runtime scripts in `volumes/data/` and `volumes/data-secondary/` through `099_core_setup_runtime_scripts.py`
+7. start a temporary `wos-init` container
+8. execute [`preinit.sh`](scripts/init/preinit.sh)
+9. execute `/usr/bin/entrypoint.sh`
+10. stop transient processes that are not needed after init
+11. execute [`postinit.sh`](scripts/init/postinit.sh)
+12. gracefully flush and stop MySQL in the init container so writes under `volumes/data/mysql/` are persisted
+13. remove the temporary init container
+
+`deploy` only starts services. It does not run initialization anymore.
+When private secondary is enabled, `deploy` and `restart` also refresh `known_hosts` for the secondary host inside `wos-primary`.
+
+## Runtime Layout
+
+```text
+instance/
+├── .config
+├── .env
+├── templates/
+└── volumes/
+    ├── data/
+    │   ├── conf/
+    │   ├── mysql/
+    │   ├── logs/
+    │   ├── backtests/
+    │   ├── CA/
+    │   ├── init/
+    │   │   ├── private/
+    │   │   └── global/
+    │   ├── start.sh
+    │   ├── start-secondary.sh
+    │   ├── healthcheck.sh
+    │   └── healthcheck-secondary.sh
+    ├── data-secondary/
+    └── ssh-shared/
+```
+
+The primary and init containers mount the full instance workspace at `/workspace`, so function hooks read:
+
+- `.env` from `/workspace/.env`
+- init templates from `/workspace/volumes/data/init/<namespace>/`
+
+`wos-primary` and `wos-secondary` keep their environment surface minimal. Most derived values stay in `.env` for compose expansion and init-time function hooks rather than being injected into the runtime containers.
+
+## Init Hooks
+
+`postinit.sh`:
+
+1. ensures `~/.my.cnf` exists
+2. creates SSH keys if missing
+3. scans `scripts/functions/<namespace>/*.py` in filename order
+4. executes only files with a numeric prefix such as `010_...`
+5. always executes scripts whose logical name contains `core`
+6. executes non-`core` scripts only when `volumes/data/init/<namespace>/<logical_name>.yml` exists
+
+Function modules are resolved by [`run_function.py`](scripts/functions/run_function.py). If `volumes/data/init/<namespace>/.state/<name>.done` exists, that step is skipped.
+
+## Feature Support
+
+The following features are supported during the `setup-private` or `setup-global` initialization phase:
+
+| Feature | Core | Description |
+| :--- | :---: | :--- |
+| `setup_namespace` | Yes | Cleans up conflicting namespace data from index tables. |
+| `setup_master` | Yes | Generates the `master.yml` configuration for the instance. |
+| `setup_gateway` | Yes | Configures the WOS gateway connection using the `WOSGW` environment variable. |
+| `setup_executable_hosts` | Yes | Registers the primary (and secondary) host architecture and SSH keys in the database. |
+| `setup_database` | No | Configures Rails `database.yml`, syncs `Previlige`/`Dirac` credentials, and manages `database_pools`. |
+| `setup_global_ctp` | No | Configures CTP client and Dirac web service INI files (Global namespace only). |
+
+"Core" features always run. Other features run only if a corresponding `.yml` configuration file exists in `templates/<namespace>/`.
+
+## Templates
+
+Built-in `.template` files are shipped under `templates/` as reference material.
+
+`.template` files are reference files only. They are not executed and are not copied into the runtime init directory automatically.
+
+To enable an optional function, create the matching `.yml` file under:
+
+- `templates/private/`
+- `templates/global/`
+
+Only `templates/<namespace>/*.yml` files are copied to `volumes/data/init/<namespace>/` and executed by `postinit.sh`.
+
+`--wosgw` is written to `.env` as `WOSGW`, and the private gateway setup step reads it directly from there.
+
+## Topology Rules
+
+- `CTP` is only supported on `x64` images.
+- On an `arm64` host, `--enable_ctp` requires `--enable_secondary`.
+- On an `x64` host, CTP runs on primary unless secondary is enabled.
+- Without `--enable_ctp`, secondary is disabled unless explicitly requested.
+
+## Ports
+
+Ports are derived from `--port-offset`:
+
+- primary SSH: `22334 + offset`
+- secondary SSH: `22434 + offset`
+- MySQL: `3306 + offset`
+- HTTP: `8000 + offset`
+- HTTPS: `4430 + offset`
+- WOS app range: `((3 + offset) * 1000 + 100)` through `+105`
+
+With the default offset `3`:
+
+- primary SSH `22337`
+- secondary SSH `22437`
+- MySQL `3309`
+- HTTP `8003`
+- HTTPS `4433`
+- WOS port range `6100-6105`
+
+## The tick-quote add-on kind (`setup-rfq`)
+
+`setup-rfq` configures a deployment folder as a **tick-quote add-on (RFQ) instance**:
+the storage ring (web backend, soldiers, storage master) + the CSV importer + its upload
+web on `/rfq/` — no time machine, dirac, samplers or privilege. Optionally the realtime
+CTP feeder runs on an x64 service with **your** CTP account.
+
+It uses the same machinery as `setup-private` (topology, `.env`, the transient `wos-init`
+cycle). The member set is the server image's own start role `WOS_ROLE=rfq`, so the image
+must carry it: images of the regular `wos-prod-s` family built from a source that has the
+role (older tags, including today's `:latest` on Docker Hub, do not). `setup-rfq` checks the
+image before initialising and stops with a clear message if the role is missing.
+`--image-tag` is required: there is no default tag, so the tool only ever pulls the tag you
+name (without it `setup-rfq` stops and names `--image-tag` and `--registry`).
+
+```bash
+wos-deploy setup-folder ./my-rfq --env prod --port-offset 37
+cd my-rfq
+wos-deploy setup-rfq -r --image-tag <tag-with-the-role>             # import-only: no credential asked
+wos-deploy deploy
+wos-deploy config      # RFQ_MASTER=localhost:<(3+offset)*1000+100>  RFQ_UPLOAD_WEB=http://localhost:<8000+offset>/rfq/api/
+```
+
+Realtime (feeder on an x64 service; on an arm64 host it runs emulated as the secondary):
+
+```bash
+export WOS_RFQ_CTP_PASSWORD=... WOS_RFQ_MARKET_PASSWORD=...    # or answer the prompts (no echo)
+wos-deploy setup-rfq -r --enable_ctp --enable_secondary --image-tag <tag> \
+    --ctp-broker-id <broker> --ctp-front tcp://<front-host>:<port> --ctp-investor-id <investor> \
+    --market-url https://<full ring>/private-api --market-account <account> --dirac-client-uuid <uuid>
+wos-deploy deploy
+wos-deploy logs wos-secondary      # [wos-rfq] lines: ini (masked), front reachability, master link, CTP login verdict
+```
+
+| Option | Meaning |
+|---|---|
+| `--registry R` | replaces the Docker Hub namespace `glacierx` in `R/wos-prod-s[-arm64]:<tag>` (e.g. a private `host:5000`); recorded as `IMAGE_REGISTRY` |
+| `--image-tag T` | **required** image tag (no default; only the named tag is pulled); recorded as `IMAGE_TAG`. `WOS_PRIMARY_IMAGE`/`WOS_SECONDARY_IMAGE` still override the whole reference |
+| `--enable_ctp` / `--enable_secondary` | the realtime feeder; same topology rules as `setup-private` (arm64 host: both flags; x64 host: on the primary unless `--enable_secondary`) |
+| `--meta-upstream HOST:PORT` | master serving `global::Market/Futures/...` for uploads with `lead_only=1` (default the own master: `lead_only=0` only) |
+| `--upload-max-bytes N` | upload limit (default 1 GiB) |
+| `--render-only [--host-arch arm64\|x64]` | write `.env` + overrides and validate `docker compose config`; no pull, no init (works without docker for the render part) |
+
+Realtime inputs, each from a flag, an environment variable of the name shown, or a prompt
+(passwords: environment or prompt only): `WOS_RFQ_CTP_BROKER_ID`, `WOS_RFQ_CTP_FRONT_END`,
+`WOS_RFQ_CTP_INVESTOR_ID`, `WOS_RFQ_CTP_PASSWORD`, `WOS_RFQ_MARKET_URL`,
+`WOS_RFQ_MARKET_ACCOUNT`, `WOS_RFQ_MARKET_PASSWORD`, `WOS_RFQ_DIRAC_CLIENT_UUID`. They are
+stored only in `./rfq-ctp.env` (mode 0600), mounted read-only into the feeder service and
+rendered there into a 0600 ini; never in `.env`, the compose config or a log. `wos-deploy config`
+shows the two endpoint addresses and prints everything else as `***`. Re-running
+`setup-rfq` re-renders everything and keeps stored inputs unless re-entered.
+
+What the developer must bring (the tool cannot provide it):
+
+| Needed | Without it |
+|---|---|
+| an image tag carrying `WOS_ROLE=rfq` | `setup-rfq: <image> has no WOS_ROLE=rfq start role ...` and nothing is initialised |
+| (realtime) a CTP account: broker id, investor id, password, a market-data front | front unreachable: `[wos-rfq] ERROR: CTP front ... is NOT reachable`, then `ERROR: no CTP login after 60 s and no answer from the front`; refused login: `ERROR: CTP login REFUSED ... OnRspUserLogin <code> (<msg>)` |
+| (realtime) an account + a client uuid on a full ring's web API (the market list) | the feeder log shows `query_markets failed status=...` and subscribes nothing |
+| (realtime) an x64 host, or amd64 emulation on arm64 | the feeder binary exists only in the amd64 image |
+| (realtime) an image whose feeder reconnects to a restarted master | after `wos-deploy restart wos-primary` an older feeder stays disconnected: restart `wos-secondary` too (the tool warns) |
+
+Data lives under `volumes/` (`volumes/data/mysql`, `volumes/data/rfq/upload`); `wos-deploy reset` wipes it.

wos_deploy/templates/docker-compose.rfq-feeder-primary.yml

@@ -0,0 +1,15 @@
+# RFQ kind, realtime enabled, feeder on the primary (an x64 host without a secondary).
+# The launcher (conf/rfq-feeder-launcher.sh, written by 100_rfq_setup_addon.py) needs
+# root to read the 0600 secrets file and render the feeder ini; start.sh runs as the ring
+# user, so the launcher is started here, in the background, before the image entrypoint.
+services:
+  wos-primary:
+    volumes:
+      - ./rfq-ctp.env:/run/wos-rfq/ctp.env:ro
+      - ./volumes/data/rfq/ctp:/home/wolverine/rfq-ctp
+    command:
+      [
+        "/bin/sh",
+        "-c",
+        "chmod +x /home/wolverine/start.sh /home/wolverine/healthcheck.sh || true; if [ -s /home/wolverine/requirements.txt ]; then /home/wolverine/.pyenv/python3/bin/pip install -r /home/wolverine/requirements.txt; fi; (bash /home/wolverine/conf/rfq-feeder-launcher.sh > /dev/null 2>&1 &); /usr/bin/entrypoint.sh; tail -f /dev/null",
+      ]

wos_deploy/templates/docker-compose.rfq-feeder-secondary.yml

@@ -0,0 +1,9 @@
+# RFQ kind, realtime enabled, feeder on the x64 secondary (an arm64 host, or an x64 host
+# with --enable_secondary). The secondary's start.sh is the feeder launcher written by
+# 100_rfq_setup_addon.py; it reads the developer's CTP / market-list settings from the
+# deployment's 0600 secrets file mounted read-only below (never from .env, never baked).
+services:
+  wos-secondary:
+    volumes:
+      - ./rfq-ctp.env:/run/wos-rfq/ctp.env:ro
+      - ./volumes/data-secondary/rfq-ctp:/home/wolverine/rfq-ctp

wos_deploy/templates/docker-compose.rfq.yml

@@ -0,0 +1,19 @@
+# The tick-quote add-on (RFQ) deployment kind -- `wos setup-rfq` -- layered on
+# docker-compose.yml. The member set comes from the server image's own start role
+# (WOS_ROLE=rfq): the image's setup, run once in the transient wos-init container,
+# generates the add-on's start.sh (storage ring + CSV importer + upload web; no time
+# machine, dirac, samplers or privilege), the importer's ini and the /rfq/ nginx
+# location. WOS_ROLE is an init selector like WOS_BACKEND_IMPL: read once, when the
+# generated layer is written. The primary only needs the importer's upload/state
+# directory on the persistent volumes/ tree (wiped by `wos reset`).
+services:
+  wos-init:
+    environment:
+      - WOS_ROLE=rfq
+      - WOS_RFQ_META_UPSTREAM=${WOS_RFQ_META_UPSTREAM:-127.0.0.1:3100}
+      - WOS_RFQ_UPLOAD_MAX_BYTES=${WOS_RFQ_UPLOAD_MAX_BYTES:-1073741824}
+    volumes:
+      - ./volumes/data/rfq/upload:/home/wolverine/backfilling_data
+  wos-primary:
+    volumes:
+      - ./volumes/data/rfq/upload:/home/wolverine/backfilling_data

wos_deploy/templates/docker-compose.secondary.yml

@@ -0,0 +1,36 @@
+services:
+  wos-secondary:
+    image: ${SECONDARY_IMAGE}
+    platform: ${SECONDARY_PLATFORM}
+    container_name: ${SECONDARY_HOSTNAME}
+    hostname: ${SECONDARY_HOSTNAME}
+    privileged: true
+    restart: always
+    tty: true
+    stdin_open: true
+    ulimits:
+      nofile:
+        soft: ${NOFILE_LIMIT:-102400}
+        hard: ${NOFILE_LIMIT:-102400}
+    ports:
+      - "${SECONDARY_SSH_PORT}:22"
+    volumes:
+      - ./volumes/data-secondary/conf:/home/wolverine/conf
+      - ./volumes/data-secondary/logs:/home/wolverine/tmp
+      - ./volumes/ssh-shared:/home/wolverine/.ssh
+      - ./volumes/data-secondary/start.sh:/home/wolverine/start.sh
+      - ./volumes/data-secondary/healthcheck.sh:/home/wolverine/healthcheck.sh
+      - ./requirements.txt:/home/wolverine/requirements.txt:ro
+    healthcheck:
+      test: ["CMD", "/home/wolverine/healthcheck.sh"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 60s
+    entrypoint: []
+    command:
+      [
+        "/bin/sh",
+        "-c",
+        "chmod +x /home/wolverine/start.sh /home/wolverine/healthcheck.sh || true; if [ -s /home/wolverine/requirements.txt ]; then /home/wolverine/.pyenv/python3/bin/pip install -r /home/wolverine/requirements.txt; fi; service ssh restart; /home/wolverine/start.sh; tail -f /dev/null",
+      ]

wos_deploy/templates/docker-compose.yml

@@ -0,0 +1,138 @@
+services:
+  wos-init:
+    image: ${PRIMARY_IMAGE}
+    platform: ${PRIMARY_PLATFORM}
+    container_name: ${INIT_HOSTNAME}
+    hostname: ${INIT_HOSTNAME}
+    privileged: true
+    tty: true
+    stdin_open: true
+    ulimits:
+      nofile:
+        soft: ${NOFILE_LIMIT:-102400}
+        hard: ${NOFILE_LIMIT:-102400}
+    environment:
+      - ENV=${ENV}
+      - NAMESPACE=${NAMESPACE}
+      - ENABLE_SECONDARY=${ENABLE_SECONDARY}
+      # The implementation selectors (wos-deploy.py INIT_SELECTOR_KEYS). Every one
+      # of them is read exactly once per instance lifetime, inside THIS container,
+      # on the boot that GENERATES start.sh; the primary re-runs that script and
+      # never re-decides. This block is therefore their authoritative landing site
+      # — the same block `re-setup` parses, so a regeneration decides the same way
+      # the original setup-* did. Deliver a value by setting it in the deploy
+      # process environment (e.g. `WOS_RING_FAMILY=rust ./wos setup-private ...`);
+      # the defaults below keep an unset selector on the image default.
+      - WOS_MIGRATE_IMPL=${WOS_MIGRATE_IMPL:-}
+      - WOS_RING_FAMILY=${WOS_RING_FAMILY:-cpp}
+      - WOS_MASTER_IMPL=${WOS_MASTER_IMPL:-}
+      - WOS_SOLDIER_IMPL=${WOS_SOLDIER_IMPL:-}
+      - WOS_BACKEND_IMPL=${WOS_BACKEND_IMPL:-}
+      - WOS_BOHR_IMPL=${WOS_BOHR_IMPL:-}
+    volumes:
+      - ./:/workspace
+      - ${DEPLOYMENT_SOURCE_DIR}:/workspace-source:ro
+      - ./volumes/data/mysql:/home/wolverine/mysql
+      - ./volumes/ssh-shared:/home/wolverine/.ssh
+    entrypoint: []
+    command: ["/bin/sh", "-c", "tail -f /dev/null"]
+    profiles:
+      - init
+
+  wos-primary:
+    image: ${PRIMARY_IMAGE}
+    platform: ${PRIMARY_PLATFORM}
+    container_name: ${PRIMARY_HOSTNAME}
+    hostname: ${PRIMARY_HOSTNAME}
+    privileged: true
+    restart: always
+    tty: true
+    stdin_open: true
+    ulimits:
+      nofile:
+        soft: ${NOFILE_LIMIT:-102400}
+        hard: ${NOFILE_LIMIT:-102400}
+    environment:
+      # storage-ring family toggle. The container
+      # supervisor (setup.py generate_start_script) reads these to pick the
+      # C++ ring (caitlyn_master/caitlyn_soldier) or the Rust ring
+      # (wos-master/wos-soldier) per role. Defaults keep the C++ ring;
+      # WOS_MASTER_IMPL / WOS_SOLDIER_IMPL override a single role when non-empty
+      # (impl = ${WOS_<ROLE>_IMPL:-${WOS_RING_FAMILY:-cpp}}).
+      - WOS_RING_FAMILY=${WOS_RING_FAMILY:-cpp}
+      - WOS_MASTER_IMPL=${WOS_MASTER_IMPL:-}
+      - WOS_SOLDIER_IMPL=${WOS_SOLDIER_IMPL:-}
+      # historical-fetch admission-control tunables for the CTM serve
+      # hub. caitlyn_time_machine resolves N (in-flight cap) / Q (backlog
+      # depth) config->env->default (8/512). Forward them here (mirroring
+      # WOS_RING_FAMILY) so a deployment tunes the cap without a rebuild; the
+      # value is carried via .env (build_env in wos-deploy.py).
+      - WOS_CTM_HISTORY_CONCURRENCY=${WOS_CTM_HISTORY_CONCURRENCY:-8}
+      - WOS_CTM_HISTORY_QUEUE_DEPTH=${WOS_CTM_HISTORY_QUEUE_DEPTH:-512}
+      # The remaining two admission-gate knobs the serve hub resolves from the
+      # environment. WEDGE_ABORT_SEC: how long the cap-level wedge sentinel
+      # tolerates a pinned-at-cap gate with static admissions before it aborts
+      # the hub (fail-fast); compiled default 1800. STATUS_SECS: the cadence of
+      # the periodic throttle-status log line (0 disables); compiled default 60.
+      # An instance that legitimately saturates the gate at boot (a large forest
+      # backfilling) needs a WEDGE_ABORT_SEC above its worst legitimate
+      # saturation, or the sentinel kills a healthy boot.
+      - WOS_CTM_HISTORY_WEDGE_ABORT_SEC=${WOS_CTM_HISTORY_WEDGE_ABORT_SEC:-1800}
+      - WOS_CTM_HISTORY_STATUS_SECS=${WOS_CTM_HISTORY_STATUS_SECS:-60}
+      # CTM boot deploy-watchdog tunables (seconds). The account plane
+      # (einstein/maxwell) starts only when every forest calculator reaches a
+      # terminal state; if the boot STALLS (a calculator never connects or hangs)
+      # the watchdog names the straggler(s) and CRASHES the CTM (fail-fast) after
+      # STALL seconds of no progress, polling every PROGRESS seconds. Carried via
+      # .env (build_env in wos-deploy.py) so a deployment tunes it without a rebuild.
+      - WOS_TM_BOOT_DEPLOY_PROGRESS_SEC=${WOS_TM_BOOT_DEPLOY_PROGRESS_SEC:-60}
+      - WOS_TM_BOOT_DEPLOY_STALL_SEC=${WOS_TM_BOOT_DEPLOY_STALL_SEC:-600}
+      # The master persist cache: its spill dir (env is the FALLBACK; the layer's
+      # generated .ini spill_dir wins), the RAM window of frames it holds before
+      # spilling, and the DISK ceiling that spill dir stops growing at. This cache is
+      # the ring's single durability layer -- dirac forwards and retains nothing, so
+      # it has neither a spill dir nor a retention switch. wos-deploy.py sets
+      # WOS_MASTER_SPILL_DIR per ring impl; the dir is bind-mounted under
+      # ./volumes/data/spill so a spilled frame survives a recreate/upgrade. Size the
+      # window from peak arrival rate x worst-case save-confirm latency: the compiled
+      # floor of 20000 frames is not a production value.
+      - WOS_MASTER_SPILL_DIR=${WOS_MASTER_SPILL_DIR:-/home/wolverine/spill/master}
+      - WOS_MASTER_RETENTION_WINDOW=${WOS_MASTER_RETENTION_WINDOW:-20000}
+      - WOS_MASTER_SPILL_HIGHWATER_BYTES=${WOS_MASTER_SPILL_HIGHWATER_BYTES:-2147483648}
+    ports:
+      - "${SSH_PORT}:22"
+      - "${DB_PORT}:3306"
+      - "${WOS_PORT_S}-${WOS_PORT_E}:3100-3105"
+      - "${HTTP_PORT}:8000"
+      - "${HTTPS_PORT}:4430"
+      # Vue (wos-web) second front-end, served by nginx on :9000.
+      - "${VUE_HTTP_PORT:-9000}:9000"
+    volumes:
+      - ./volumes/data/conf:/home/wolverine/conf
+      - ./volumes/data/conf/backend/config:/home/wolverine/backend/config
+      - ./volumes/data/mysql:/home/wolverine/mysql
+      - ./volumes/data/.my.cnf:/home/wolverine/.my.cnf
+      - ./volumes/data/backtests:/home/wolverine/backtests
+      - ./volumes/data/logs:/home/wolverine/tmp
+      - ./volumes/data/CA:/home/wolverine/CA
+      # the PER-LAYER durable spill tree (spill/{dirac,master,
+      # wos-master}) under the persistent volumes/ tree so spilled frames survive
+      # a container upgrade/recreate. wos-deploy.py provisions the per-layer subdirs.
+      - ./volumes/data/spill:/home/wolverine/spill
+      - ./volumes/ssh-shared:/home/wolverine/.ssh
+      - ./volumes/data/start.sh:/home/wolverine/start.sh
+      - ./volumes/data/healthcheck.sh:/home/wolverine/healthcheck.sh
+      - ./requirements.txt:/home/wolverine/requirements.txt:ro
+    healthcheck:
+      test: ["CMD", "/home/wolverine/healthcheck.sh"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 60s
+    entrypoint: []
+    command:
+      [
+        "/bin/sh",
+        "-c",
+        "chmod +x /home/wolverine/start.sh /home/wolverine/healthcheck.sh || true; if [ -s /home/wolverine/requirements.txt ]; then /home/wolverine/.pyenv/python3/bin/pip install -r /home/wolverine/requirements.txt; fi; /usr/bin/entrypoint.sh; tail -f /dev/null",
+      ]

wos_deploy/templates/scripts/__init__.py

@@ -0,0 +1 @@
+"""Deployment scripts package."""

wos_deploy/templates/scripts/functions/__init__.py

@@ -0,0 +1 @@
+"""Deployment function package."""

wos_deploy/templates/scripts/functions/common/__init__.py

@@ -0,0 +1 @@
+"""Shared function implementations."""