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

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

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

3.7 KiB Raw Blame History