archy/apps/DEVELOPMENT.md

# Archipelago Apps — Development Guide

## App Overview

### Bitcoin & Lightning
| App | Ports | Version |
|-----|-------|---------|
| bitcoin-knots | 8332 (RPC), 8333 (P2P) | v28.1 |
| lnd | 9735 (P2P), 10009 (gRPC), 8080 (REST) | v0.17.4-beta |
| btcpay-server | 23000 (HTTP) | v1.13.5 |
| thunderhub | 3010 (HTTP) | v0.13.31 |
| mempool | 4080 (HTTP) | v2.5.0 |
| electrumx | 50001 (TCP), 50002 (SSL) | latest |
| fedimint | 8173 (API), 8174 (Web) | v0.10.0 |

### Nostr
| App | Ports | Version |
|-----|-------|---------|
| nostr-rs-relay | 8081 (WebSocket) | v0.9.0 |
| nostrudel | 8082 (HTTP) | v0.40.0 |

### Self-Hosted
| App | Port | Version |
|-----|------|---------|
| nextcloud | 8084 | v28 |
| jellyfin | 8096 | v10.8.13 |
| immich | 2283 | release |
| photoprism | 2342 | v240915 |
| vaultwarden | 8222 | v1.30.0-alpine |
| homeassistant | 8123 | v2024.1 |
| filebrowser | 8083 | v2.27.0 |
| searxng | 8888 | 2024.11.17 |
| ollama | 11434 | v0.5.4 |
| grafana | 3001 | v10.2.0 |
| portainer | 9000 | v2.19.4 |
| penpot | 8089 | v2.4 |

## Building Apps

```bash
cd apps
./build.sh           # Build all custom apps
./build.sh <app-id>  # Build specific app
```

Custom apps with local source: `router`, `did-wallet`, `web5-dwn`. All other apps use official container images.

## App Structure

Each app directory contains:
- `manifest.yml` — Container configuration
- `Dockerfile` — Image definition (custom apps only)
- `README.md` — App-specific docs (custom apps only)
- `src/` — Source code (custom apps only)

## Running in Development

The Archipelago backend manages containers via rootless Podman. Install and start apps through the web UI Marketplace or via RPC:

```bash
curl -X POST http://localhost:5959/rpc/v1 \
  -H "Content-Type: application/json" \
  -d '{"method": "container-install", "params": {"manifest_path": "apps/router/manifest.yml"}}'
```

### Manual Testing (Podman)

```bash
# Build
./build.sh router

# Run directly with Podman
podman run -p 18084:8080 \
  -v /tmp/archipelago-dev/router:/app/data \
  localhost/archipelago/router:latest
```

## Integration Checklist

Adding a new app requires updates in multiple places. See the full checklist in [CLAUDE.md](../CLAUDE.md) under "App Integration Checklist".

## Port Assignments

See [PORTS.md](./PORTS.md) for complete mapping. Dev ports are offset by +10000.