Add proper instructions

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:<version>
+```
+
+#### API Server
+```shell
+cd server
+docker build . -t bitfeed/server:<version>
+```
+
+## 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.

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

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
+```shell
-
-Install the dependencies...
-
-```bash
 npm install
 ```
 
-...then start [Rollup](https://rollupjs.org):
+#### Running in development
-
+```shell
-```bash
 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 for production
-
+```shell
-
-
-#### Building and running in production mode
-
-To create an optimised version of the app:
-
-```bash
 npm run build
 ```

client/public/env.js

@@ -1,5 +0,0 @@
-window.injected = {
-  TARGET: 'public',
-  OVERRIDE_BACKEND_HOST: 'localhost',
-  OVERRIDE_BACKEND_PORT: 4000
-}

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"),
+  // if this instance is public-facing, enables e.g. analytics
-  backend: window.injected.OVERRIDE_BACKEND_HOST,
+  target: getInjectedEnv('TARGET'),
-  backendPort: window.injected.OVERRIDE_BACKEND_PORT,
+  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,
 }

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"

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:
+```shell
-```
-MIX_ENV=prod
-RELEASE_NODE=bitfeed
-```
-
-then run
-
-```
 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
+```

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