diff --git a/DOCKER.md b/DOCKER.md new file mode 100644 index 0000000..ce3e17d --- /dev/null +++ b/DOCKER.md @@ -0,0 +1,32 @@ +# Running Bitfeed with Docker + +## Images + +Client and server container images are automatically built for each tagged release and available from the [Github Container Registry](https://github.com/bitfeed-project?tab=packages&repo_name=bitfeed): + +Use like +```yml +image: ghcr.io/bitfeed-project/bitfeed-client:v2.1.2 +``` + +```yml +image: ghcr.io/bitfeed-project/bitfeed-server:v2.1.2 +``` + +Alternatively, build your own containers from source using the provided Dockerfiles: + +#### Front end client +```shell +cd client +docker build . -t bitfeed/client: +``` + +#### API Server +```shell +cd server +docker build . -t bitfeed/server: +``` + +## Orchestration + +Check out [`docker-compose.yml`](https://github.com/bitfeed-project/bitfeed/blob/master/docker-compose.yml) for an example configuration, which exposes the front end client on port 3000, and connects to a locally running Bitcoin node. \ No newline at end of file diff --git a/README.md b/README.md index 61454cc..7389951 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,41 @@ This repo hosts the code behind [Bitfeed](https://bits.monospace.live), a live v ![Bitfeed](https://github.com/bitfeed-project/bitfeed/blob/master/screenshot.png) -## Installation +## Running Bitfeed + +#### Options + +- One-click home node integrations + - [Umbrel](https://getumbrel.com) (coming soon) + - [Citadel](https://runcitadel.space/) +- [Docker](https://github.com/bitfeed-project/bitfeed/blob/master/DOCKER.md) +- [Build from source](https://github.com/bitfeed-project/bitfeed/blob/master/README.md#installing-and-building-bitfeed) + +## Installing and Building Bitfeed + +Clone the repo + +```shell +git clone https://github.com/bitfeed-project/bitfeed.git +cd bitfeed +``` + +Then check out the README.md files in the [client](https://github.com/bitfeed-project/bitfeed/tree/master/client) and [server](https://github.com/bitfeed-project/bitfeed/tree/master/server) directories for instructions on building, running and developing. -> instructions coming soon ## Contributing -> instructions coming soon +Contributions of all kinds are extremely welcome: + + - Pull Requests for + - typos + - bug fixes + - new features + - coding best practices + - translations + - Opening new issues for + - any of the above + - feature suggestions + - Testing + - Sharing Bitfeed with friends + - Financial support diff --git a/client/README.md b/client/README.md index b064d8d..2af6367 100644 --- a/client/README.md +++ b/client/README.md @@ -1,37 +1,29 @@ -# Bitfeed +## Building and Running the Bitfeed Front End Client -This repo hosts the code behind Bitfeed (bits.monospace.live), which is a live visualization of Bitcoin network activity, focusing on the journey from unconfirmed transactions to confirmed blocks. +#### Prerequisites + - [Node](https://nodejs.dev/download/) + - NPM + - Nginx (production deployment only) + - [API server](https://github.com/bitfeed-project/bitfeed/blob/master/server) -## Installing +#### Configuration -Install on a local machine or hardware node to run a personal copy of the visualization. +`client/src/config.js` exposes a number of configuration options, mostly useful for local development. -### Prerequisites +When developing the front end, you can point at the hosted backend API server instead of running your own full node and server instance by setting `backend` to `"bits.monospace.live"` and `backendPort` to `null`. -The Bitfeed server relies on a local instance of Bitcoin Core, compiled with ZeroMQ enabled. Fee-related data requires an unpruned node with txindex=1. +#### Installation -## Contributing - -Install the dependencies... - -```bash +```shell npm install ``` -...then start [Rollup](https://rollupjs.org): - -```bash +#### Running in development +```shell npm run dev ``` -Navigate to [localhost:5000](http://localhost:5000). You should see your app running. Edit a component file in `src`, save it, and reload the page to see your changes. - - - -#### Building and running in production mode - -To create an optimised version of the app: - -```bash +#### Building for production +```shell npm run build -``` \ No newline at end of file +``` diff --git a/client/public/env.js b/client/public/env.js index f169859..e69de29 100644 --- a/client/public/env.js +++ b/client/public/env.js @@ -1,5 +0,0 @@ -window.injected = { - TARGET: 'public', - OVERRIDE_BACKEND_HOST: 'localhost', - OVERRIDE_BACKEND_PORT: 4000 -} diff --git a/client/src/config.js b/client/src/config.js index c5c1a76..7db83fb 100644 --- a/client/src/config.js +++ b/client/src/config.js @@ -1,15 +1,33 @@ +function getInjectedEnv (key, fallback) { + if (window.injected && window.injected[key] != null) { + return window.injected[key] + } + return fallback +} + export default { dev: ENVIRONMENT === 'development', + // external API for processing donations, retrieving donor info & message bar content donationRoot: 'https://donate.monospace.live', + // enables some additional logging & debugging tools debug: false, + // enables an additional square packing algorithm debugging tool layoutHints: false, - public: (window.injected.TARGET === "public"), - backend: window.injected.OVERRIDE_BACKEND_HOST, - backendPort: window.injected.OVERRIDE_BACKEND_PORT, + // if this instance is public-facing, enables e.g. analytics + target: getInjectedEnv('TARGET'), + public: (getInjectedEnv('TARGET', 'dev') === "public"), + // host & port of the backend API websocket server + backend: getInjectedEnv('OVERRIDE_BACKEND_HOST'), // do not include the protocol + backendPort: getInjectedEnv('OVERRIDE_BACKEND_PORT'), + // Whether to connect to the backend server over ws:// or wss:// secureSocket: (window.location.protocol === 'https:'), + // Disables the transaction feed nofeed: false, + // Minimum delay in ms before newly recieved transactions enter the visualization txDelay: 10000, donationsEnabled: true, + // Enables the message bar messagesEnabled: true, + // Delay in ms between message bar rotations alertDuration: 20000, } diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..7bf56ef --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,29 @@ +version: "2.1" + +services: + web: + image: bitfeed/client + restart: on-failure + stop_grace_period: 1m + depends_on: + - "api" + environment: + TARGET: "docker" + BACKEND_HOST: "api" + BACKEND_PORT: "5000" + ports: + - "3000:80" + + api: + image: bitfeed/server + user: "1000:1000" + restart: on-failure + stop_grace_period: 1m + environment: + PORT: "5000" + BITCOIN_HOST: "172.17.0.1" + BITCOIN_ZMQ_RAWBLOCK_PORT: "29000" + BITCOIN_ZMQ_RAWTX_PORT: "29001" + BITCOIN_RPC_PORT: "8332" + BITCOIN_RPC_USER: "bitcoin" + BITCOIN_RPC_PASS: "correcthorsebatterystaple" diff --git a/server/README.md b/server/README.md index bda1690..8d88f02 100644 --- a/server/README.md +++ b/server/README.md @@ -1,18 +1,56 @@ -# Bitfeed Server +## Building and Running the Bitfeed API Server -**TODO** +#### Prerequisites + - [Elixir](https://elixir-lang.org/install.html) + - [Bitcoin Full Node](https://bitcoin.org/en/full-node) + - unpruned + - indexed + - running in server mode + - with ZMQ enabled + - [(see an example bitcoin.conf file here)](https://github.com/bitfeed-project/bitfeed/blob/master/server/bitcoin.conf.example) -## Deployment +#### Installation -set the following environment variables: -``` -MIX_ENV=prod -RELEASE_NODE=bitfeed -``` - -then run - -``` +```shell mix do deps.get +mix do deps.compile +``` + +#### Configuration + +The API server expects the following environment variables to be set: + +| variable | usage | +|---|---| +| MIX_ENV | compilation environment, either "prod" or "dev" | +| PORT | Port to expose the API (front end connects to this) | +| BITCOIN_HOST | Bitcoin node host address | +| BITCOIN_ZMQ_RAWBLOCK_PORT | Bitcoin node ZMQ port for block events (to match `zmqpubrawblock` in bitcoin.conf) | +| BITCOIN_ZMQ_RAWTX_PORT | Bitcoin node ZMQ port for transaction events (to match `zmqpubrawtx` in bitcoin.conf) | +| BITCOIN_RPC_PORT | Bitcoin node RPC port | +| either | | +| BITCOIN_RPC_USER | Bitcoin node RPC user | +| BITCOIN_RPC_PASS | Bitcoin node RPC password | +| or | | +| BITCOIN_RPC_COOKIE | absolute path to a Bitcoin node RPC authentication .cookie file | + + +#### Running in development + +Compile and run in an interactive local shell: + +```shell +iex -S mix +``` + +#### Building for production + +```shell mix release ``` + +#### Running production build + +```shell +_build/prod/rel/prod/bin/prod start +``` diff --git a/server/bitcoin.conf.example b/server/bitcoin.conf.example new file mode 100644 index 0000000..20855da --- /dev/null +++ b/server/bitcoin.conf.example @@ -0,0 +1,20 @@ +# Generated by https://jlopp.github.io/bitcoin-core-config-generator/ + +# This config should be placed in following path: +# ~/.bitcoin/bitcoin.conf + +# [core] +# Maintain a full transaction index, used by the getrawtransaction rpc call. +txindex=1 + +# [rpc] +# Accept command line and JSON-RPC commands. +server=1 +rpcallowip=127.0.0.1 + +# [zmq] +zmqpubrawblock=tcp://127.0.0.1:29000 +zmqpubrawtx=tcp://127.0.0.1:29001 +zmqpubhashtx=tcp://127.0.0.1:29000 +zmqpubhashblock=tcp://127.0.0.1:29000 +zmqpubsequence=tcp://127.0.0.1:29002