diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 7e6803f..4924a53 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -13,8 +13,6 @@ concurrency: jobs: build: if: github.event.pull_request.draft == false - uses: start9labs/shared-workflows/.github/workflows/build.yml@master - # with: - # FREE_DISK_SPACE: true + uses: Start9Labs/start-technologies/.github/workflows/build.yml@master secrets: DEV_KEY: ${{ secrets.DEV_KEY }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 3b83acf..6dcef4a 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -7,9 +7,8 @@ on: jobs: release: - uses: start9labs/shared-workflows/.github/workflows/release.yml@master + uses: Start9Labs/start-technologies/.github/workflows/release.yml@master with: - # FREE_DISK_SPACE: true RELEASE_REGISTRY: ${{ vars.RELEASE_REGISTRY }} S3_S9PKS_BASE_URL: ${{ vars.S3_S9PKS_BASE_URL }} secrets: diff --git a/.github/workflows/tagAndRelease.yml b/.github/workflows/tagAndRelease.yml index 2706fe5..c4031d3 100644 --- a/.github/workflows/tagAndRelease.yml +++ b/.github/workflows/tagAndRelease.yml @@ -11,10 +11,9 @@ concurrency: jobs: tag: - uses: start9labs/shared-workflows/.github/workflows/tagAndRelease.yml@master + uses: Start9Labs/start-technologies/.github/workflows/tagAndRelease.yml@master with: REFERENCE_REGISTRY: ${{ vars.REFERENCE_REGISTRY }} - # FREE_DISK_SPACE: true RELEASE_REGISTRY: ${{ vars.RELEASE_REGISTRY }} S3_S9PKS_BASE_URL: ${{ vars.S3_S9PKS_BASE_URL }} secrets: diff --git a/AGENTS.md b/AGENTS.md index fe7e122..f687e1c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,17 @@ # AGENTS.md -You are working in a StartOS service-package repository — a repo that builds a `.s9pk` for installation on StartOS. +This is a StartOS service-package repository — it builds a `.s9pk` for StartOS. -**Before doing anything in this repo, read [CONTRIBUTING.md](./CONTRIBUTING.md) and every document it links to.** That covers what this package is, how it's built, how it ships, and the conventions to follow. Do not begin work until you have read them all. +Develop it inside a StartOS packaging workspace created by `start-cli s9pk init-workspace`, +which provides the packaging guide and agent context one level up. If you're reading this in a +bare clone with no workspace, the full guide is at . + +Work this package's `TODO.md` from top to bottom. Keep `README.md` (architecture, for developers and LLMs) and `instructions.md` (end-user docs) in sync with your changes. + +## This repo + +- **Package id is `utxoracle`.** Depends (hard-required) on `bitcoind` for local JSON-RPC and chain data; mounts only Bitcoin's `main` volume read-only for the RPC cookie and keeps no state of its own. Exports a single `ui` interface on port 80. The run mode is chosen with the `configure` action and passed to `utxoracle.py` via the `UTXORACLE_MODE` env var. + +## Inspecting a running install + +To run a command inside the service's container (read its generated config, grep app logs), use `start-cli package attach utxoracle -n utxoracle-sub -- `. Select the subcontainer by **name** with `-n` (the name passed to `SubContainer.of` in `main.ts` — here `utxoracle-sub`) or by image with `-i`. Note: `-s/--subcontainer` matches the internal **Guid**, not the name, so passing a name to `-s` fails with "no matching subcontainers". diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index cfb9e8c..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,43 +0,0 @@ -# Contributing - -## Keep these in sync - -- **[`README.md`](./README.md)** — what this package is and how it's built (image, volumes, interfaces). Technical reference for developers and AI assistants. -- **[`instructions.md`](./instructions.md)** — the user-facing instructions packed into the `.s9pk` and shown on the **Instructions** tab in StartOS, for the person running the service. -- **[`TODO.md`](./TODO.md)** — pending work on this package. - -**Read all three before starting any work.** Any code change that affects user-visible behavior must update `README.md` and `instructions.md` in the same change; add to `TODO.md` when you defer work, and remove items when complete. Content rules: [Writing READMEs](https://docs.start9.com/packaging/writing-readmes.html), [Writing Instructions](https://docs.start9.com/packaging/writing-instructions.html). - -## Environment setup - -See [Environment Setup](https://docs.start9.com/packaging/environment-setup.html) - -## Building - -```bash -npm ci # install dependencies -make # build the universal .s9pk -``` - -For a complete list of build options, see [Makefile](https://docs.start9.com/packaging/makefile.html). - -## Updating the upstream version - -1. Apply the upstream bump per [UPDATING.md](./UPDATING.md). -2. Update `version` and `releaseNotes` in `startos/versions/current.ts` — the latest version always lives in that file, so an in-place edit is all most bumps need. A new file is spun off only when the bump requires a migration — see [Versions](https://docs.start9.com/packaging/versions.html). - -## CI/CD - -Three workflows under `.github/workflows/` wrap reusable workflows in [`start9labs/shared-workflows`](https://github.com/Start9Labs/shared-workflows): - -- **`build.yml`** — on PR, builds the `.s9pk` and uploads per-arch artifacts for sideload testing. -- **`release.yml`** — on `v*` tag, builds per arch and publishes to the test registry. -- **`tagAndRelease.yml`** — on push to `main`, creates a StartOS version tag and runs `release.yml`, skipping if already in production. - -Promotion to `beta` and `prod` is a separate, manual step. - -## How to contribute - -1. Fork the repository and create a branch from `main`. -2. Make your changes — including the doc updates above. -3. Open a pull request to `main`. diff --git a/Dockerfile b/Dockerfile index 491ad3d..6bfdc07 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,6 +1,6 @@ FROM python:3.11-slim -# UTXOracle itself is pure Python stdlib and talks to Bitcoin Core over JSON-RPC. +# UTXOracle itself is pure Python stdlib and talks to Bitcoin over JSON-RPC. # curl is only used by the entrypoint's RPC readiness probe. RUN apt-get update && apt-get install -y --no-install-recommends curl && \ rm -rf /var/lib/apt/lists/* diff --git a/Makefile b/Makefile index 10d4360..8315da3 100644 --- a/Makefile +++ b/Makefile @@ -1,3 +1,3 @@ ARCHES := x86 arm # overrides to s9pk.mk must precede the include statement -include s9pk.mk +include node_modules/@start9labs/start-sdk/s9pk.mk diff --git a/README.md b/README.md index e8e626c..8a4882e 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ UTXOracle estimates the price of bitcoin by analyzing patterns in local on-chain transaction data. This StartOS package runs UTXOracle against the -Bitcoin Core service on the same server and serves the generated result page +Bitcoin service on the same server and serves the generated result page through a web interface. ## Image and Container Runtime @@ -20,12 +20,12 @@ through a web interface. This package is a thin wrapper around upstream UTXOracle. The image is `python:3.11-slim` with `utxoracle.py` vendored **verbatim** from (see `UPDATING.md`) plus the StartOS -entrypoint. UTXOracle talks to Bitcoin Core over JSON-RPC using only the Python +entrypoint. UTXOracle talks to Bitcoin over JSON-RPC using only the Python standard library — there is no `bitcoin-cli` and no raw block-file access. -The entrypoint writes a `bitcoin.conf` pointing at the StartOS Bitcoin Core +The entrypoint writes a `bitcoin.conf` pointing at the StartOS Bitcoin service, shows a temporary status page, starts the web server, waits for Bitcoin -Core RPC readiness, runs the unmodified script, and serves the HTML chart it +RPC readiness, runs the unmodified script, and serves the HTML chart it produces as `index.html`. If UTXOracle exits with an error, the web server keeps running and the status page is replaced with a failure page. @@ -38,17 +38,17 @@ recomputed on each run. Its only persistence is the run-mode setting, stored by StartOS in `store.json` on the `startos` volume (read in `startos/main.ts`, not mounted into the container). -The Bitcoin Core dependency volume is mounted read-only at `/mnt/bitcoind` so +The Bitcoin dependency volume is mounted read-only at `/mnt/bitcoind` so UTXOracle can read the RPC cookie (`/mnt/bitcoind/.cookie`) for authentication. -All block data is fetched over JSON-RPC from the local Bitcoin Core service; the +All block data is fetched over JSON-RPC from the local Bitcoin service; the package does not read raw block files. ## Installation and First-Run Flow -Install Bitcoin Core on the same StartOS server before starting UTXOracle. +Install Bitcoin on the same StartOS server before starting UTXOracle. The entrypoint generates the `bitcoin.conf` that points UTXOracle at the local -Bitcoin Core service; no RPC username or password is generated or stored by this -package (it uses Bitcoin Core's cookie). +Bitcoin service; no RPC username or password is generated or stored by this +package (it uses Bitcoin's cookie). When the service starts, the web interface becomes available first with a temporary status page. The final UTXOracle result page appears after block @@ -59,8 +59,12 @@ analysis completes. The run mode (`rb` for today, `yesterday`, or a `YYYY/MM/DD` date) lives in `store.json` on the `startos` volume. `startos/main.ts` reads it and passes it to the container as the `UTXORACLE_MODE` environment variable. Set it through the -Configure action. The Bitcoin Core RPC connection is separate: the entrypoint -generates a `bitcoin.conf` at startup. +Configure action. The Bitcoin RPC connection is separate: `startos/main.ts` +resolves Bitcoin's bound RPC interface over the internal StartOS bridge and +passes its host and port to the container as the `RPC_HOST`/`RPC_PORT` +environment variables, which the entrypoint writes into a `bitcoin.conf` at +startup. While the address is unresolved the variables are absent and the +entrypoint waits for Bitcoin rather than dialing a placeholder. ## Network Access and Interfaces @@ -85,7 +89,7 @@ run. ## Backups and Restore Backups include the `startos` volume (the run-mode setting). Restore uses the -standard StartOS SDK backup flow for that volume. The Bitcoin Core dependency +standard StartOS SDK backup flow for that volume. The Bitcoin dependency volume is not backed up by this package. ## Health Checks @@ -97,20 +101,20 @@ volume is not backed up by this package. ## Dependencies -Bitcoin Core is required. The dependency version range and required health +Bitcoin is required. The dependency version range and required health checks are declared in `startos/dependencies.ts`. -UTXOracle uses Bitcoin Core for JSON-RPC calls with RPC cookie authentication. -The Bitcoin Core dependency volume is mounted read-only solely to read the +UTXOracle uses Bitcoin for JSON-RPC calls with RPC cookie authentication. +The Bitcoin dependency volume is mounted read-only solely to read the cookie file. ## Limitations and Differences -1. UTXOracle connects only to the Bitcoin Core service on the same StartOS +1. UTXOracle connects only to the Bitcoin service on the same StartOS server. 2. The web interface is a static HTTP server that serves the generated UTXOracle result page. -3. UTXOracle does not store Bitcoin Core RPC usernames or passwords. +3. UTXOracle does not store Bitcoin RPC usernames or passwords. 4. The result page updates when the service is run again; this package does not provide a live streaming price feed. @@ -142,6 +146,8 @@ dependencies: - bitcoind startos_managed_env_vars: - UTXORACLE_MODE + - RPC_HOST + - RPC_PORT actions: - configure health_checks: diff --git a/UPDATING.md b/UPDATING.md index 746fc3d..e39d93b 100644 --- a/UPDATING.md +++ b/UPDATING.md @@ -18,7 +18,7 @@ The version is named in the banner near the top of the file (currently "Version curl -fsSL https://utxo.live/oracle/UTXOracle.py -o utxoracle.py ``` - This package does **not** patch the script — it is a thin wrapper. `docker_entrypoint.sh` supplies a `bitcoin.conf` (RPC host/port/cookie) pointing at the StartOS Bitcoin Core service and serves the HTML the script produces, so the upstream script runs unmodified. After updating, confirm upstream still reads `bitcoin.conf` for `rpcconnect`/`rpcport`/`rpccookiefile` and still writes an `UTXOracle_*.html` file; if those conventions change, adjust `docker_entrypoint.sh` (never the script). + This package does **not** patch the script — it is a thin wrapper. `docker_entrypoint.sh` supplies a `bitcoin.conf` (RPC host/port from the `RPC_HOST`/`RPC_PORT` env vars StartOS injects — `startos/main.ts` resolves Bitcoin's bound RPC interface over the internal bridge — plus the cookie path) pointing at the StartOS Bitcoin service and serves the HTML the script produces, so the upstream script runs unmodified. After updating, confirm upstream still reads `bitcoin.conf` for `rpcconnect`/`rpcport`/`rpccookiefile` and still writes an `UTXOracle_*.html` file; if those conventions change, adjust `docker_entrypoint.sh` (never the script). **Privacy:** the entrypoint also strips the upstream "Live Updating Oracle" promo and its autoplay YouTube `