Skip to content

PLAN.md

Latest commit

 

History

History
104 lines (77 loc) · 3.37 KB

PLAN.md

File metadata and controls

104 lines (77 loc) · 3.37 KB

Development Plan – Umbrel App Bisq

1. Project Scope

  • Goal: Run Bisq Daemon on Umbrel as a full node, integrated with Bitcoin Core, accessible via Tor.
  • Node Type: User-facing, always-on daemon. Not targeting Bisq infrastructure roles (seed, oracle, price node, explorer).
  • Future: Prepare for Bisq mobile apps (iOS/Android) that can connect remotely to this node.

2. Target Architecture

  • bisq: Bisq Daemon (Java) with persistent volume /data/bisq.
  • app_proxy: Umbrel reverse proxy for authentication and Tor integration.
  • ui/bridge (optional): Small web UI or gRPC-to-HTTP bridge for dashboard usage.
  • Bitcoin Core: Connects to Umbrel’s Bitcoin Core through P2P and optionally RPC.
  • Tor: Provides hidden service for remote mobile access.

3. Action Plan

Phase A – Repository Setup

  • Create repo with structure:

/apps/bisq/
docker-compose.yml
umbrel-app.yml
exports.sh
README.md
/docker/Dockerfile.bisq
/docs/PLAN.md
/ui/ (optional)
  • Setup GitHub Actions workflow to build and push multi-arch images (arm64 + amd64).

Phase B – Bisq Daemon Image

  • Base image: eclipse-temurin:17-jre.
  • Download bisq-daemon from official releases.
  • Run as non-root user.
  • Entrypoint example:
java -jar /opt/bisq/daemon.jar \
  --apiPassword=$BISQ_API_PASSWORD \
  --btcNodes=$BISQ_BTC_NODES \
  $BISQ_EXTRA_FLAGS

Phase C – Umbrel Packaging

  • docker-compose.yml: services bisq, app_proxy, optional ui.
  • umbrel-app.yml: app metadata (id, name, version, tagline, dependencies).
  • exports.sh: expose variables if needed (e.g., API host/port).
  • Configure proxy authentication (PROXY_AUTH_ADD or PROXY_AUTH_WHITELIST).

Phase D – Bitcoin Core Integration

  • Use environment exports from Umbrel Bitcoin app:

    • $APP_BITCOIN_NODE_IP
    • $APP_BITCOIN_P2P_PORT
    • $APP_BITCOIN_RPC_* (if needed for DAO validation)

  • Pass into Bisq via --btcNodes.

  • Optional: disable Tor for Bitcoin P2P (--useTorForBtc=false).

Phase E – Testing

  • Use umbrel-dev to run app locally (OrbStack, WSL2, or Linux).
  • Validate persistence: restart app and confirm /data/bisq survives.
  • Test on both arm64 (Raspberry Pi) and x86_64.

Phase F – Publication

  • Community App Store: host your own using the template.
  • Official Umbrel Store: open a PR to getumbrel/umbrel-apps.

4. Risks & Considerations

  • Resources: Bitcoin Core requires large disk space (1–2 TB recommended).
  • Security: Protect API password and Bisq seed phrase.
  • Persistence: Backup /data/bisq regularly.
  • Networking: Ensure Tor hidden service is correctly configured for remote access.

5. References

6. Roadmap

  1. M0 – PoC: Build image, test Bisq API locally.
  2. M1 – Bitcoin Core: Connect Bisq to Umbrel Bitcoin node.
  3. M2 – Packaging: Add docker-compose.yml and umbrel-app.yml.
  4. M3 – Secure API: Password, Tor hidden service.
  5. M4 – Optional UI: gRPC-to-HTTP bridge + small web frontend.
  6. M5 – Documentation & Release: Write user guide, submit to app store.