Initial commit
This commit is contained in:
zazawowow
126
docs/app-manifest-spec.md
Normal file
126
docs/app-manifest-spec.md
Normal file
@@ -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
|
||||
165
docs/architecture.md
Normal file
165
docs/architecture.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# Archipelago Bitcoin Node OS - Architecture Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
Archipelago is a next-generation Bitcoin Node OS built on Alpine Linux with Podman containerization, combining the modularity of Parmanode with the security and efficiency of a minimal server OS.
|
||||
|
||||
## System Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Alpine Linux Base (130MB) │
|
||||
│ - Minimal kernel │
|
||||
│ - Hardened security │
|
||||
│ - Read-only root filesystem │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌───────────────┼───────────────┐
|
||||
│ │ │
|
||||
┌───────▼──────┐ ┌──────▼──────┐ ┌─────▼──────┐
|
||||
│ Podman │ │ Rust Backend│ │ Vue.js UI │
|
||||
│ (rootless) │ │ (core/) │ │ (neode-ui/) │
|
||||
└───────┬──────┘ └──────┬──────┘ └─────────────┘
|
||||
│ │
|
||||
└───────┬───────┘
|
||||
│
|
||||
┌───────────▼───────────┐
|
||||
│ Container Orchestration│
|
||||
│ Layer (new) │
|
||||
│ - Manifest parser │
|
||||
│ - Podman client │
|
||||
│ - Dependency resolver │
|
||||
│ - Health monitor │
|
||||
└───────────┬───────────┘
|
||||
│
|
||||
┌───────────▼───────────┐
|
||||
│ Containerized Apps │
|
||||
│ - Bitcoin Core │
|
||||
│ - LND / CLN │
|
||||
│ - BTCPay Server │
|
||||
│ - Nostr Relays │
|
||||
│ - Meshtastic │
|
||||
│ - Web5 DWN │
|
||||
└───────────────────────┘
|
||||
```
|
||||
|
||||
## Key Components
|
||||
|
||||
### 1. Alpine Linux Base
|
||||
|
||||
- **Size**: ~130MB (vs 1.5GB+ for Umbrel/StartOS)
|
||||
- **Security**: Hardened kernel, minimal attack surface
|
||||
- **Multi-arch**: ARM64 (Raspberry Pi) and x86_64 support
|
||||
|
||||
### 2. Container Orchestration Layer
|
||||
|
||||
Located in `core/container/`:
|
||||
- **manifest.rs**: Parses YAML app manifests
|
||||
- **podman_client.rs**: Wraps Podman API for container management
|
||||
- **dependency_resolver.rs**: Resolves app dependencies and conflicts
|
||||
- **health_monitor.rs**: Monitors container health and auto-restarts
|
||||
|
||||
### 3. Backend API Extensions
|
||||
|
||||
New RPC endpoints in `core/startos/src/container/`:
|
||||
- `container-install`: Install app from manifest
|
||||
- `container-start/stop/remove`: Container lifecycle
|
||||
- `container-status/logs`: Status and debugging
|
||||
- `container-list`: List all containers
|
||||
- `container-health`: Health status aggregation
|
||||
|
||||
### 4. Vue.js UI Integration
|
||||
|
||||
New components in `neode-ui/`:
|
||||
- **ContainerApps.vue**: List of containerized apps
|
||||
- **ContainerAppDetails.vue**: Detailed app view with logs
|
||||
- **ContainerStatus.vue**: Status indicator component
|
||||
- **container-client.ts**: API client for container operations
|
||||
- **container.ts**: Pinia store for container state
|
||||
|
||||
### 5. App Manifest System
|
||||
|
||||
Standardized YAML format in `apps/`:
|
||||
- Defines container image, resources, dependencies
|
||||
- Security policies and health checks
|
||||
- Bitcoin/Lightning/Web5 integration metadata
|
||||
|
||||
### 6. Parmanode Compatibility
|
||||
|
||||
Located in `core/parmanode/`:
|
||||
- **script_runner.rs**: Executes Parmanode scripts in containers
|
||||
- **converter.rs**: Converts Parmanode modules to app manifests
|
||||
- **parmanode-wrapper.sh**: Shell wrapper for direct script execution
|
||||
|
||||
### 7. Security Modules
|
||||
|
||||
Located in `core/security/`:
|
||||
- **container_policies.rs**: Generates AppArmor/SELinux profiles
|
||||
- **secrets_manager.rs**: Encrypted secrets storage
|
||||
- **image_verifier.rs**: Cosign signature verification
|
||||
|
||||
### 8. Performance Optimization
|
||||
|
||||
Located in `core/performance/`:
|
||||
- **resource_manager.rs**: CPU/memory/disk allocation
|
||||
- **optimize-alpine.sh**: OS-level optimizations
|
||||
|
||||
## App Categories
|
||||
|
||||
### Bitcoin & Lightning
|
||||
- Bitcoin Core (full node)
|
||||
- LND (Lightning Network Daemon)
|
||||
- Core Lightning (CLN)
|
||||
- BTCPay Server
|
||||
- Mempool (blockchain explorer)
|
||||
|
||||
### Web5 & Decentralized Protocols
|
||||
- Nostr relays (nostr-rs-relay, strfry)
|
||||
- Web5 DWN (Decentralized Web Node)
|
||||
- DID Wallet
|
||||
- Bitcoin Domain Names
|
||||
|
||||
### Mesh Networking & Routing
|
||||
- Meshtastic (LoRa mesh networking)
|
||||
- Router (mesh routing, device discovery)
|
||||
- Local network management
|
||||
|
||||
### Self-Hosted Services
|
||||
- Home Assistant
|
||||
- Grafana
|
||||
- SearXNG
|
||||
- OnlyOffice
|
||||
- Ollama (local AI)
|
||||
- Penpot
|
||||
|
||||
## Security Model
|
||||
|
||||
1. **OS Level**: Hardened Alpine, read-only root, minimal kernel
|
||||
2. **Container Level**: Rootless Podman, capability dropping, network isolation
|
||||
3. **Secrets**: Encrypted storage, runtime injection only
|
||||
4. **Supply Chain**: Signed images (Cosign), SBOM generation
|
||||
5. **Network**: Firewall, rate limiting, Tor integration
|
||||
6. **Audit**: Immutable logs, configuration tracking
|
||||
|
||||
## Networking
|
||||
|
||||
- **Isolated Networks**: Each app on separate bridge network by default
|
||||
- **Bitcoin Core**: Isolated network, explicit RPC access
|
||||
- **Lightning Nodes**: Separate network, gRPC/REST exposed
|
||||
- **Tor Integration**: Optional, default for privacy-sensitive apps
|
||||
- **Mesh Networking**: Meshtastic and router support for decentralized communication
|
||||
|
||||
## Data Persistence
|
||||
|
||||
- **App Data**: `/var/lib/archipelago/{app-id}/`
|
||||
- **Secrets**: `/var/lib/archipelago/secrets/{app-id}/` (encrypted)
|
||||
- **Logs**: `/var/lib/archipelago/logs/{app-id}/`
|
||||
- **Backups**: `/var/lib/archipelago/backups/`
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- Time-travel snapshots (ZFS/BTRFS)
|
||||
- Decentralized app marketplace (IPFS + Nostr)
|
||||
- Multi-node clustering
|
||||
- Hardware attestation (TPM 2.0)
|
||||
- Protocol-agnostic design (multi-chain support)
|
||||
Reference in New Issue
Block a user