archy/apps/DEVELOPMENT.md

Archipelago Apps - Development Guide

This directory contains all prepackaged containerized applications for Archipelago NodeOS.

App Overview

Bitcoin & Lightning

• bitcoin-core: Full Bitcoin node (ports: 8332, 8333) - v24.0.0
• lnd: Lightning Network Daemon (ports: 9735, 10009, 8080)
• core-lightning: Core Lightning implementation (ports: 9736, 9835)
• lightning-stack: Complete Lightning implementation (ports: 9737, 10010, 8087) - v0.12.0
• btcpay-server: Bitcoin payment processor (ports: 80, 443) - v1.12.0
• mempool: Blockchain explorer (port: 4080) - v2.5.0
• fedimint: Federated Bitcoin minting (ports: 8173, 8174) - v0.3.0

Nostr Relays

• nostr-rs-relay: High-performance Rust relay (port: 8081)
• strfry: Lightweight C++ relay (port: 8082)

Web5 & Decentralized Protocols

• web5-dwn: Decentralized Web Node (port: 3000)
• did-wallet: Web5 DID Wallet (port: 8083)

Self-Hosted Services

• home-assistant: Home automation (port: 8123) - v2024.1.0
• grafana: Monitoring and dashboards (port: 3001) - v10.2.0
• ollama: Local AI models (port: 11434) - v0.1.0
• searxng: Privacy search engine (port: 8888) - v2024.1.0
• onlyoffice: Office suite (port: 8088) - v7.5.0
• penpot: Design platform (port: 8089) - v2.0.0

Custom Applications

• endurain: Application platform (port: 8085) - v1.0.0
• morphos-server: MorphOS server (port: 8086) - v1.0.0

Mesh Networking

• router: Mesh routing and network management (ports: 8084, 5353, 1900)
• meshtastic: LoRa mesh networking (ports: 4403, 1883)

Port Assignments

All apps use unique base ports. In development mode, ports are offset by 10000 (configurable).

See PORTS.md for complete port mapping.

Key apps:

• bitcoin-core: 8332, 8333 → 18332, 18333
• btcpay-server: 80, 443 → 10080, 10443
• home-assistant: 8123 → 18123
• grafana: 3001 → 13001
• mempool: 4080 → 14080
• ollama: 11434 → 21434
• lightning-stack: 9737, 10010, 8087 → 19737, 20010, 18087

Building Apps

Build All Apps

./build.sh

Build Specific App

./build.sh <app-id>

Build for Development

./build.sh <app-id> --dev

App Structure

Each app directory contains:

• manifest.yml - App manifest defining container configuration
• Dockerfile - Container image definition
• README.md - App-specific documentation (for custom apps)
• Source code (for custom apps: router, did-wallet, web5-dwn)

Custom Apps

The following apps have custom implementations:

1. router - TypeScript/Node.js mesh router
2. did-wallet - TypeScript/Node.js Web5 wallet
3. web5-dwn - TypeScript/Node.js DWN server

These apps can be developed locally:

cd apps/<app-id>
npm install
npm run dev

Standard Apps

The following apps use official Docker images:

• bitcoin-core (bitcoin/bitcoin:26.0)
• lnd (lightninglabs/lnd:v0.18.0)
• core-lightning (elementsproject/lightningd:v23.08.2)
• btcpay-server (btcpayserver/btcpayserver:1.12.0)
• nostr-rs-relay (scsibug/nostr-rs-relay:latest)
• strfry (strfry/strfry:latest)
• meshtastic (meshtastic/meshtastic:latest)

Running in Development

Using Archipelago Backend

The Archipelago backend will automatically:

1. Build local images if they don't exist
2. Apply port offsets in dev mode
3. Map volumes to /tmp/archipelago-dev/<app-id>
4. Start containers with proper networking

Manual Testing

You can test apps manually:

# Build the app
./build.sh <app-id>

# Run with Docker/Podman
docker run -p <host-port>:<container-port> \
  -v /tmp/archipelago-dev/<app-id>:/data \
  archipelago/<app-id>:latest

Integration with Archipelago

Apps are integrated via:

1. Manifest files - Define app configuration
2. Container runtime - Podman/Docker for execution
3. Port manager - Handles port allocation and offsets
4. Dev orchestrator - Manages containers in development

Next Steps

When building the OS image, these apps will be:

1. Built into container images
2. Included in the OS image
3. Available for installation via the UI
4. Pre-configured with proper networking and security