From a18a2f3d8da60e3e2c5a5e1b4d1ed8c5d2b6c984 Mon Sep 17 00:00:00 2001 From: Adam Soltys Date: Tue, 17 Mar 2026 00:11:30 -0700 Subject: update readme --- README.md | 123 +++++++++++++++++++++++++++++++++-------------------- compose.yml.sample | 2 +- 2 files changed, 77 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 82e90a37..1b6fcd31 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # Coinos -Coinos is a web-based bitcoin and nostr client. You can use it as a front end to your personal bitcoin and lightning nodes or host a public instance that allows anyone to register with a username and password. Try ours at https://coinos.io +A bitcoin web wallet with built-in support for Lightning, Liquid, Nostr, and Ark. Run it as a personal wallet on top of your own node, or deploy a public instance like [coinos.io](https://coinos.io). -This repository contains the code for the API server. The frontend code is at https://github.com/coinos/coinos-ui +This repo is the API server. The frontend is at [coinos/coinos-ui](https://github.com/coinos/coinos-ui). -## Quick Start (regtest) +## Getting Started ```bash git clone https://github.com/coinos/coinos-server.git @@ -12,79 +12,108 @@ cd coinos-server ./setup.sh ``` -The setup script handles everything automatically: +That's it. The script installs Docker if needed, downloads a pre-built regtest snapshot with funded wallets and Lightning channels, pulls ~500MB of container images, and starts everything. Takes a few minutes on first run. -- Installs Docker if needed (Linux) -- Downloads a pre-built regtest snapshot (~2MB) with wallets, blocks, and Lightning channels -- Pulls container images (~500MB total, all sharing a common base) -- Starts all services +``` +API server http://localhost:3119 +Block explorer http://localhost:3000 +Nostr relay ws://localhost:7777 +``` -If the snapshot isn't available, it falls back to generating everything from scratch (wallets, blocks, channels). Use `./setup.sh --no-snapshot` to force this. +Start the frontend in a separate terminal: -After setup: +```bash +cd ~/coinos-ui && bun dev +``` -| Service | URL | -|---|---| -| API server | http://localhost:3119 | -| Esplora (block explorer) | http://localhost:3000 | -| Nostr relay | ws://localhost:7777 | +### Requirements -To start the frontend: `cd ~/coinos-ui && bun dev` +- Linux or macOS (Docker auto-installed on Linux; install [Docker Desktop](https://docs.docker.com/desktop/install/mac-install/) on macOS) +- ~2GB disk space -## Requirements +## How It Works -- Linux or macOS -- [Docker](https://docs.docker.com/get-docker/) with the Compose plugin -- ~2GB free disk space +The server runs as a set of Docker containers orchestrated by `compose.yml`: -On Linux, the setup script installs Docker automatically. On macOS, install [Docker Desktop](https://docs.docker.com/desktop/install/mac-install/) first. +| Container | Image | What it does | +|-----------|-------|-------------| +| **app** | coinos-base | API server (Hono/Bun), bind-mounted from this repo | +| **bc** | bitcoin:30.2 | Bitcoin Core (regtest) | +| **lq** | elements:23.3.2 | Liquid sidechain | +| **cl, clb, clc** | lightningd:v25.12.1 | Core Lightning nodes (3 for testing) | +| **db** | valkey:8.0-alpine | User data (Redis-compatible) | +| **tb** | tigerbeetle | Double-entry accounting ledger | +| **sf** | strsrv | Nostr relay (strfry) | +| **cs** | chopsticks | Block explorer API | +| **eb** | electrs | Electrum server | +| **arc** | kvrocks | Archive cache (RocksDB-backed) | -## Architecture +All `ghcr.io/coinos/*` images share a common base layer (~196MB downloaded once). -**Core services** (always running): -- **Coinos Server** — Hono/Bun API server -- **[Bitcoin Core](https://github.com/bitcoin/bitcoin)** — Bitcoin node (regtest) -- **[Core Lightning](https://docs.corelightning.org/)** — Lightning Network (3 nodes for testing) -- **[Valkey](https://valkey.io/)** — Redis-compatible database -- **[TigerBeetle](https://tigerbeetle.com/)** — Double-entry accounting ledger -- **[Liquid](https://liquid.net/)** — Bitcoin sidechain -- **[strfry](https://github.com/hoytech/strfry)** — Nostr relay -- **[Esplora](https://github.com/nicolgit/nigiri)** — Block explorer API (Chopsticks + Electrs) -- **[Kvrocks](https://kvrocks.apache.org/)** — Archive cache +### Optional Services -**Optional** (commented out in `compose.yml`, uncomment to enable): -- **[Ark](https://arkade.fun/)** — Off-chain UTXO protocol -- **[Cashu Nutshell](https://github.com/cashubtc/nutshell)** — Ecash mint +Uncomment in `compose.yml` to enable: -All `asoltys/*` images share a common `coinos-base` layer, so Docker only downloads the base once. +- **Ark** (arkd, arkd-wallet, nbxplorer) — off-chain UTXO protocol +- **Cashu** (nutshell) — ecash mint backed by Lightning -## Useful Commands +## Development ```bash # Mine a block docker exec bc bitcoin-cli -regtest generatetoaddress 1 \ $(docker exec bc bitcoin-cli -regtest getnewaddress) -# Check Lightning node +# Lightning CLI docker exec cl lightning-cli --network=regtest getinfo +docker exec cl lightning-cli --network=regtest listpeerchannels -# View logs +# Logs docker compose logs -f app # Restart a service docker compose restart app -# Stop everything +# Stop / start docker compose down +docker compose up -d +``` + +### Project Structure + +``` +config.ts App configuration (from config.ts.sample) +compose.yml Docker services (from compose.yml.sample) +data/ Runtime data for all services (gitignored) +lib/ Core libraries (payments, lightning, ark, etc.) +routes/ HTTP route handlers +setup.sh One-command dev environment setup +sampledata/ Default configs copied to data/ on first run +``` -# Regenerate the regtest snapshot (maintainers) -./setup.sh snapshot +### Reset + +```bash +rm -rf data config.ts compose.yml +./setup.sh ``` -## Configuration +### Rebuild from Scratch + +To skip the snapshot and generate wallets/blocks/channels manually: + +```bash +./setup.sh --no-snapshot +``` + +## Contributing + +1. Fork and clone +2. Run `./setup.sh` +3. Make changes — the app container bind-mounts this directory, so edits are live +4. `bun test` to run tests +5. Open a PR -- `config.ts` — App config (generated from `config.ts.sample`) -- `compose.yml` — Docker Compose services (generated from `compose.yml.sample`) -- `data/` — Runtime data for all services +## License -To reset: `rm -rf data config.ts compose.yml` and re-run `./setup.sh`. +MIT diff --git a/compose.yml.sample b/compose.yml.sample index d9621d4a..c56c668e 100644 --- a/compose.yml.sample +++ b/compose.yml.sample @@ -28,7 +28,7 @@ services: - ./data/bitcoin:/home/bitcoin/.bitcoin restart: always lq: - image: ghcr.io/coinos/elements:23.2.4 + image: ghcr.io/coinos/elements:23.3.2 container_name: lq volumes: - ./data/liquid:/home/elements/.elements -- cgit v1.2.3