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)
• lnd: Lightning Network Daemon (ports: 9735, 10009, 8080)
• core-lightning: Core Lightning implementation (ports: 9736, 9835)
• btcpay-server: Bitcoin payment processor (ports: 80, 443)

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)

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).

App	Base Ports	Dev Ports (offset +10000)
bitcoin-core	8332, 8333	18332, 18333
lnd	9735, 10009, 8080	19735, 20009, 18080
core-lightning	9736, 9835	19736, 19835
btcpay-server	80, 443	10080, 10443
nostr-rs-relay	8081	18081
strfry	8082	18082
did-wallet	8083	18083
router	8084, 5353, 1900	18084, 15353, 11900
web5-dwn	3000	13000
meshtastic	4403, 1883	14403, 11883

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