Update doc

2026-09-10 13:12:35 +02:00
parent d5e5b78334
commit e15f00e98c
4 changed files with 135 additions and 60 deletions
@@ -1,32 +1,66 @@
-# btcprice
-
-Bitcoin price tracker UI. Serves an HTML page with live price updates streamed from [btcdata](../btcdata) via WebSocket using HTMX.
-
-## Quick Start
-
-```bash
-# Start btcdata first (provides price data)
-cd ../btcdata && make run
-
-# Local dev
-make run       # starts on port 4000
-make tailwind  # watch Tailwind CSS (separate terminal)
-
-# Docker (starts both btcprice + btcdata)
-docker compose up -d   # btcprice on 4041, btcdata on 4101
-```
-
-## Environment Variables
-
-| Variable | Default | Description |
-|---|---|---|
-| `PORT` | `4000` | HTTP server port |
-| `BTCDATA_URL` | `http://192.168.50.42:4100` | btcdata service URL (browser connects via WebSocket) |
-
-## How It Works
-
-The server renders an HTML page with HTMX and the WebSocket extension (`hx-ext="ws"`). HTMX connects directly to btcdata's WebSocket endpoint (`BTCDATA_URL/api/price/ws`), which sends HTML fragments. HTMX swaps the received `<div id="price-display">` into the DOM automatically. Price changes are color-coded (green up, red down). Reconnection is handled by HTMX with exponential backoff.
-
-## Tech Stack
-
-Clojure · Kit · Undertow · Reitit · Hiccup · HTMX · Tailwind CSS v4
+# btcprice
+
+Bitcoin price tracker UI. Serves an HTML page with live price updates streamed from
+[btcdata](../btcdata), which this server proxies over WebSocket and renders as HTML fragments
+for HTMX.
+
+## Quick Start
+
+```bash
+# Start btcdata first (provides price data)
+cd ../btcdata && make run
+
+# Local dev — creates .venv and installs requirements on first run
+make run       # starts on port 4000
+make tailwind  # watch Tailwind CSS (separate terminal)
+```
+
+Optionally `cp .env.example .env` to override `BTCDATA_URL`; without it the code default
+(`http://localhost:4100`) applies. `make run-local` requires a `.env` defining
+`BTCDATA_LOCAL_URL`.
+
+## Docker
+
+`docker compose up -d` starts **btcprice only** — it does not bring up btcdata. Both compose
+files attach to the external `btc-network`, so create it once and start btcdata separately:
+
+```bash
+docker network create btc-network      # once
+cd ../btcdata && docker compose up -d
+cd ../btcprice && docker compose up -d
+```
+
+| Service  | Local dev      | Docker                                |
+|----------|----------------|---------------------------------------|
+| btcprice | localhost:4000 | localhost:4041 (container port 4040)  |
+| btcdata  | localhost:4100 | localhost:4102                        |
+
+Inside `btc-network`, btcprice reaches btcdata as `http://btcdata:4102`.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `BTCDATA_URL` | `http://localhost:4100` | btcdata service URL the server proxies to |
+| `BTCDATA_LOCAL_URL` | — | Used by `make run-local` instead of `BTCDATA_URL` |
+| `DOCKER_BTCDATA_PORT` | `4102` | btcdata's port inside `btc-network` (compose only) |
+
+The HTTP port is not configurable via environment: `make run` hardcodes 4000 and the Docker
+image's `CMD` hardcodes 4040.
+
+## How It Works
+
+The browser loads a page with HTMX and the WebSocket extension, which connects back to
+**btcprice** at `/ws/price` and `/ws/strike` — the browser never contacts btcdata directly.
+
+Each of those endpoints opens an upstream WebSocket to btcdata (`/api/price/ws` and
+`/api/strike/ws`), converts each JSON message to an HTML fragment (`price_json_to_html`,
+`strike_json_to_html`), and forwards it to the browser. HTMX swaps the received
+`<div id="price-display">` / `<div id="strike-display">` into the DOM. Price changes are
+color-coded (green up, red down). Reconnection is handled by HTMX.
+
+## Tech Stack
+
+Python · FastAPI · Uvicorn · websockets · HTMX · Tailwind CSS v4
+
+The Clojure implementation this replaced is on the `clojure` branch.