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
onlyoffice	8088	v7.5.1
penpot	8089	v2.4

Building Apps

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:

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)

# 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 under "App Integration Checklist".

Port Assignments

See PORTS.md for complete mapping. Dev ports are offset by +10000.