# 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

```bash
./build.sh
```

### Build Specific App

```bash
./build.sh <app-id>
```

### Build for Development

```bash
./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:

```bash
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:

```bash
# 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