@kadi.build/deploy-ability 0.0.2 → 0.0.4

package/docs/STORAGE.md

@@ -1,318 +0,0 @@
-## 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" }]
-      }
-    }
-  }
-};
-```
-
----
-