OBLITERATUS/docs/deployment/shared-gpu-host.md

Shared GPU Host Deployment

This document defines the supported shape for preparing OBLITERATUS on a GPU host used by more than one person. It is a deployment contract, not a claim that the current Gradio process provides tenant isolation.

Supported initial mode

Install one immutable, administrator-owned release. The preferred isolation is per-user CLI execution, but a dedicated no-login service account may run one explicitly shared trusted-team UI on loopback. Keep these boundaries separate:

Boundary	Requirement
Release	Read-only to users; selected by an atomic current symlink
Workspace	One directory per Unix identity; mode 0700
Model cache	Per-user by default; shared caches must be administrator-owned and read-only
Outputs	Per-user, quota-controlled, and excluded from backups unless explicitly promoted
Credentials	Per-user file, systemd credential, or trusted broker; never a shared environment file
GPU	Acquired through the host scheduler/lease broker before CUDA initialization
Network	CLI over SSH; any UI listens on loopback behind authenticated ingress

Do not grant users write access to the release checkout, virtual environment, service units, wrapper scripts, or another user's cache. Do not put users in the Docker group merely to run OBLITERATUS; Docker group membership is effectively root access.

Gradio limitation

The current UI keeps loaded-model metadata and cleanup controls in process-global state. A single shared process can therefore expose or remove another user's session artifacts. Basic authentication controls entry but does not create tenant isolation.

Until per-session artifact ownership, authorization, quotas, and cleanup tests exist, use one of these modes:

1. shared CLI installation with private Unix workspaces (recommended);
2. one UI process per user, bound to loopback on a distinct port; or
3. a dedicated service account serving one trusted research team through one explicitly shared workspace, bound to loopback.

Do not expose the UI directly on 0.0.0.0. Gradio --share links are also not an approved production ingress mechanism.

GPU coordination contract

Static nvidia-smi checks do not prevent races. A host scheduler must reserve the requested devices and VRAM before OBLITERATUS initializes CUDA, maintain the lease for the entire process, and release it after CUDA allocations terminate.

Schedulers that drain another inference service commonly distinguish acquire from ready. OBLITERATUS does not yet emit a portable post-model-load readiness signal. Such deployments must not mark a lease ready immediately after process start; add and test an application readiness hook first.

The requested VRAM must include weights, activation collection, verification, checkpoint snapshots, CUDA context, and a safety margin. Multi-GPU sharding is a capacity feature, not a general throughput multiplier.

Filesystem layout

A conventional layout is:

/srv/obliteratus/
├── releases/<commit>/       # administrator-owned source and .venv
├── current -> releases/...  # atomic promotion target
├── users/<login>/           # mode 0700 workspaces and per-user caches
├── catalog/                 # optional administrator-curated read-only models
└── staging/                 # release verification before promotion

Large model checkpoints and rewritten outputs require a dedicated filesystem. Set capacity and inode alerts, per-user quotas, and a retention policy before allowing downloads. A safe default is no automatic backup of reproducible model caches and outputs; back up only configs, reports, provenance, and explicitly promoted research artifacts.

Release and rollback

1. Select an immutable signed tag or reviewed commit.
2. Verify the source artifact and supply-chain evidence described in the release process.
3. Build the locked environment in a new release directory.
4. Run installer/scripts/verify.sh on the target CUDA host.
5. Run a small, pinned-model smoke job through the real GPU scheduler.
6. Atomically repoint current only after all checks pass.
7. Retain the previous release until the observation window ends.

Rollback is an atomic symlink reversal followed by termination and restart of new work. Do not change the release beneath a running job.

Activation gate

Production activation requires all of the following:

• dedicated storage mounted and monitored;
• named users/groups and private workspace creation tested;
• GPU lease integration with a truthful post-load readiness signal;
• pinned release and locked CUDA environment verified;
• credential isolation and telemetry policy documented;
• smoke test, failure test, cancellation test, and rollback test passed;
• operator runbook and host inventory published outside the application repo.