archy/docs/app-manifest-spec.md

# 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