Initial commit

docs/app-manifest-spec.md

@@ -0,0 +1,126 @@
+# App Manifest Specification
+
+## Overview
+
+App manifests define containerized applications in Archipelago. They use YAML format and specify container configuration, dependencies, resources, security policies, and integration metadata.
+
+## File Location
+
+App manifests are stored in `apps/{app-id}/manifest.yml`
+
+## Schema
+
+### Required Fields
+
+```yaml
+app:
+  id: string              # Unique app identifier (lowercase, kebab-case)
+  name: string            # Human-readable name
+  version: string          # Semantic version (e.g., "1.0.0")
+  container:
+    image: string         # Container image (e.g., "bitcoin/bitcoin:26.0")
+```
+
+### Optional Fields
+
+```yaml
+app:
+  description: string      # App description
+  
+  container:
+    image_signature: string  # Cosign signature URL (e.g., "cosign://...")
+    pull_policy: string      # "if-not-present" | "always" | "never"
+  
+  dependencies:
+    - storage: string        # Minimum disk space (e.g., "500Gi")
+    - app_id: string        # Required app dependency
+      version: string        # Version constraint (e.g., ">=26.0")
+    - string                # Simple app dependency
+  
+  resources:
+    cpu_limit: number       # CPU cores (e.g., 2)
+    memory_limit: string    # Memory limit (e.g., "2Gi", "512Mi")
+    disk_limit: string      # Disk limit (e.g., "500Gi")
+  
+  security:
+    capabilities: [string]  # Linux capabilities (e.g., ["NET_BIND_SERVICE"])
+    readonly_root: boolean  # Read-only root filesystem (default: true)
+    network_policy: string  # "isolated" | "host" | network name
+    apparmor_profile: string # AppArmor profile name
+  
+  ports:
+    - host: number          # Host port
+      container: number     # Container port
+      protocol: string      # "tcp" | "udp" (default: "tcp")
+  
+  volumes:
+    - type: string          # "bind" | "tmpfs" | "volume"
+      source: string        # Host path
+      target: string        # Container path
+      options: [string]     # Mount options (e.g., ["rw", "noexec"])
+  
+  environment:
+    - string                # Environment variable (e.g., "NETWORK=mainnet")
+  
+  devices:
+    - string                # Device path (e.g., "/dev/ttyUSB0")
+  
+  health_check:
+    type: string            # "http" | "exec"
+    endpoint: string        # HTTP URL or command
+    path: string            # HTTP path (for http type)
+    interval: string        # Check interval (e.g., "30s")
+    timeout: string         # Timeout (e.g., "5s")
+    retries: number         # Failure retries (default: 3)
+  
+  # Integration-specific metadata
+  bitcoin_integration:
+    rpc_access: string      # "admin" | "read-only"
+    sync_required: boolean  # Requires synced node
+    testnet_support: boolean
+    pruning_support: boolean
+  
+  lightning_integration:
+    channel_management: boolean
+    payment_routing: boolean
+  
+  nostr_integration:
+    relay_type: string      # "public" | "private"
+    monetization_enabled: boolean
+    event_storage: string   # "sqlite" | "postgres"
+  
+  web5_integration:
+    did_support: boolean
+    dwn_protocol: boolean
+    sync_enabled: boolean
+  
+  networking:
+    mesh_enabled: boolean
+    local_network_access: boolean
+    device_discovery: boolean
+    routing_protocols: [string]  # e.g., ["olsr", "babel"]
+```
+
+## Examples
+
+See `apps/` directory for complete examples:
+- `apps/bitcoin-core/manifest.yml`
+- `apps/lnd/manifest.yml`
+- `apps/nostr-rs-relay/manifest.yml`
+- `apps/meshtastic/manifest.yml`
+
+## Validation
+
+Manifests are validated on installation:
+- Required fields present
+- Version format valid
+- Resource limits reasonable
+- Port conflicts detected
+- Dependency cycles prevented
+
+## Versioning
+
+- Use semantic versioning (MAJOR.MINOR.PATCH)
+- Breaking changes increment MAJOR
+- New features increment MINOR
+- Bug fixes increment PATCH