# 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](./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

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