@kadi.build/deploy-ability 0.0.1

package/docs/STORAGE.md

@@ -0,0 +1,318 @@
+## Understanding Storage Configuration
+
+One of the most common questions when configuring deployments is: **"What's the difference between memory and storage?"**
+
+This section explains how to configure resources in your `agent.json` deployment profiles.
+
+### Three Types of Resources
+
+When deploying containers, you work with three distinct resource types:
+
+| Resource | Medium | Speed | Volatility | Use Cases |
+|----------|--------|-------|------------|-----------|
+| **memory** | RAM | Nanoseconds | Lost on crash | Running processes, hot caches, application state |
+| **ephemeralStorage** | Disk | Milliseconds | Lost on restart | Container root FS, /tmp, temporary files, logs |
+| **persistentVolumes** | Disk | Milliseconds | Survives restarts | Database files, user uploads, ML models |
+
+### Memory vs Storage
+
+**Memory (RAM):**
+- **What it is:** System memory for your application's runtime
+- **Speed:** Extremely fast (nanoseconds)
+- **Cleared:** Immediately when container stops or crashes
+- **Use for:** JavaScript heap, database query cache, in-memory data structures
+- **Example:** A Node.js process with `"memory": "1Gi"` can use up to 1GB RAM
+
+**Ephemeral Storage (Disk):**
+- **What it is:** The container's root filesystem (where your code runs)
+- **Speed:** Slower than RAM but faster than network (milliseconds)
+- **Cleared:** When container **restarts** (intentional or crash)
+- **Use for:** Container's root filesystem (`/`, `/tmp`, `/var/log`), temporary processing files
+- **Example:** A container needs space for binaries, system files, and temporary logs
+
+**Persistent Volumes (Disk):**
+- **What it is:** Named disk volumes mounted at specific paths
+- **Speed:** Similar to ephemeral storage (milliseconds)
+- **Cleared:** **Never** (persists for the lease duration, survives restarts)
+- **Use for:** Database files, user uploads, ML model weights, config that must survive restarts
+- **Example:** PostgreSQL data directory at `/var/lib/postgresql/data`
+
+### Real-World Analogy
+
+Think of your deployment like an office workspace:
+
+- **Memory (RAM)** = Your **desk**
+  - Everything you're actively working on right now
+  - Instant access
+  - Cleared when you leave (container stops)
+
+- **Ephemeral Storage** = **Whiteboard in your office**
+  - Quick access for temporary notes
+  - Walk a few steps to get there
+  - Erased at end of day (container restarts)
+
+- **Persistent Storage** = **Filing cabinet**
+  - Long-term storage for important documents
+  - Slower to access (open drawer, find file)
+  - Stays forever (survives restarts, persists for lease)
+
+### Configuration Format
+
+Here's how to configure resources in your `agent.json`:
+
+```json
+{
+  "deploy": {
+    "my-profile": {
+      "target": "akash",
+      "network": "mainnet",
+      "services": {
+        "gateway": {
+          "image": "my-app:latest",
+          "resources": {
+            "cpu": 0.5,
+            "memory": "1Gi",
+            "ephemeralStorage": "512Mi",
+            "persistentVolumes": [
+              {
+                "name": "data",
+                "size": "10Gi",
+                "mount": "/data",
+                "class": "beta2"
+              }
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**What this means:**
+- **cpu: 0.5** → Half a CPU core for processing
+- **memory: "1Gi"** → 1GB RAM for Node.js runtime, request handling, caches
+- **ephemeralStorage: "512Mi"** → 512MB disk for container root FS, /tmp, logs
+- **persistentVolumes** → 10GB disk mounted at `/data` that survives restarts
+
+### Storage Classes (Persistent Volumes Only)
+
+When using persistent volumes, you can specify the storage class (performance tier):
+
+| Class | Type | Speed | Cost | Use Cases |
+|-------|------|-------|------|-----------|
+| **beta1** | HDD | Slow | Cheapest | Cold storage, backups, archives |
+| **beta2** | SSD | Balanced | Moderate | Most workloads, databases, general purpose |
+| **beta3** | NVMe | Fastest | Most expensive | High-IOPS databases, real-time processing |
+| **ram** | Memory | Ultra-fast | Very expensive | Ultra-low latency, temporary in-memory storage |
+
+**Recommendation:** Use `beta2` (SSD) for most workloads. Only upgrade to `beta3` if you need high IOPS.
+
+### Example Configurations
+
+#### Simple API Server (No Persistent Storage)
+
+```json
+{
+  "resources": {
+    "cpu": 0.5,
+    "memory": "512Mi",
+    "ephemeralStorage": "1Gi"
+  }
+}
+```
+
+**Why:** A stateless API server doesn't need persistent storage. Everything runs in memory or ephemeral disk.
+
+---
+
+#### Database Server (Persistent Storage Required)
+
+```json
+{
+  "resources": {
+    "cpu": 2,
+    "memory": "4Gi",
+    "ephemeralStorage": "2Gi",
+    "persistentVolumes": [
+      {
+        "name": "pgdata",
+        "size": "50Gi",
+        "mount": "/var/lib/postgresql/data",
+        "class": "beta2"
+      }
+    ]
+  }
+}
+```
+
+**Why:** PostgreSQL needs persistent storage for database files. If the container restarts without it, all data is lost!
+
+---
+
+#### LLM Inference Server (Large Model Weights)
+
+```json
+{
+  "resources": {
+    "cpu": 4,
+    "memory": "16Gi",
+    "ephemeralStorage": "10Gi",
+    "persistentVolumes": [
+      {
+        "name": "models",
+        "size": "100Gi",
+        "mount": "/models",
+        "class": "beta3"
+      }
+    ],
+    "gpu": {
+      "units": 1,
+      "attributes": {
+        "vendor": {
+          "nvidia": [{ "model": "rtx4090" }]
+        }
+      }
+    }
+  }
+}
+```
+
+**Why:**
+- **16Gi memory** → Large RAM for model inference
+- **10Gi ephemeral** → Space for temporary request processing
+- **100Gi persistent (NVMe)** → Fast storage for loading 70B+ model weights
+- **GPU** → Required for fast inference
+
+---
+
+#### Multi-Volume Setup (Cache + Data)
+
+```json
+{
+  "resources": {
+    "cpu": 1,
+    "memory": "2Gi",
+    "ephemeralStorage": "1Gi",
+    "persistentVolumes": [
+      {
+        "name": "data",
+        "size": "20Gi",
+        "mount": "/data",
+        "class": "beta2"
+      },
+      {
+        "name": "cache",
+        "size": "10Gi",
+        "mount": "/cache",
+        "class": "beta1"
+      }
+    ]
+  }
+}
+```
+
+**Why:** Separate volumes for critical data (SSD) and less critical cache (HDD for cost savings).
+
+### Common Mistakes to Avoid
+
+**Confusing memory with storage**
+```json
+// WRONG - Trying to use memory for file storage
+"memory": "50Gi"  // Expensive! Use persistentVolumes instead
+```
+
+**Correct approach**
+```json
+"memory": "4Gi",  // Only for runtime
+"persistentVolumes": [
+  { "name": "data", "size": "50Gi", ... }  // For file storage
+]
+```
+
+---
+
+**Not using persistent volumes for databases**
+```json
+// WRONG - Database data will be LOST on restart!
+"ephemeralStorage": "50Gi"
+```
+
+**Correct approach**
+```json
+"ephemeralStorage": "2Gi",  // Just for root FS
+"persistentVolumes": [
+  { "name": "db", "size": "50Gi", "mount": "/var/lib/postgresql/data", "class": "beta2" }
+]
+```
+
+---
+
+**Forgetting ephemeralStorage**
+```json
+// WRONG - Missing ephemeralStorage (will use default 1Gi)
+"resources": {
+  "cpu": 1,
+  "memory": "2Gi",
+  "persistentVolumes": [...]
+}
+```
+
+**Correct approach**
+```json
+"resources": {
+  "cpu": 1,
+  "memory": "2Gi",
+  "ephemeralStorage": "2Gi",  // Explicitly set
+  "persistentVolumes": [...]
+}
+```
+
+### Quick Decision Guide
+
+**Use this flowchart to decide what storage you need:**
+
+```
+Need to store data?
+├─ No → Just set memory + ephemeralStorage
+├─ Yes → Does it need to survive restarts?
+   ├─ No → Use ephemeralStorage (temporary files, caches)
+   └─ Yes → Use persistentVolumes
+      └─ How fast does it need to be?
+         ├─ Normal → beta2 (SSD)
+         ├─ Very fast → beta3 (NVMe)
+         └─ Cost-sensitive → beta1 (HDD)
+```
+
+### TypeScript Types
+
+For programmatic deployment, here are the relevant TypeScript types:
+
+```typescript
+import type { ResourceRequirements, PersistentVolumeSpec } from 'deploy-ability';
+
+const resources: ResourceRequirements = {
+  cpu: 0.5,
+  memory: "1Gi",              // RAM for application runtime
+  ephemeralStorage: "512Mi",  // Container root filesystem
+  persistentVolumes: [        // Optional: named volumes
+    {
+      name: "data",
+      size: "10Gi",
+      mount: "/data",
+      class: "beta2"  // Optional: defaults to beta2
+    }
+  ],
+  gpu: {  // Optional: GPU requirements
+    units: 1,
+    attributes: {
+      vendor: {
+        nvidia: [{ model: "rtx4090" }]
+      }
+    }
+  }
+};
+```
+
+---
+