@bpanel/bpanel
v0.3.0-alpha
Published
GUI application to interact with a Bcoin Bitcoin node
Downloads
54
Readme
Welcome to bPanel!
This is the official repo for the bPanel project, a full featured, enterprise level GUI for your bcoin Bitcoin node.
For complete developer and API documentation, visit our website: https://bpanel.org
Table of Contents
Dependencies
- npm >= 5.7.1
- node >= 8.9.4
NOTE: It is important to be using at least this version of npm
because of a bug that removes node_modules
that are installed from
GitHub and doesn't reinstall them which breaks the build.
Quick Start
With an existing Node
If you already have a bcoin node running that you would like to use bPanel to
interact with, add the relevant configurations (uri
, api-key
, network
etc.)
to a configuration file ~/.bpanel/clients/default.conf
and run:
npm install
npm start
You can save as many confs for as many compatible nodes as you want and use
the argument client-id
to connect to them. For example, save another set
of configurations to a file ~/.bpanel/clients/main.conf
and run:
npm start -- --client-id=main
Configurations can also be passed via the command line or environment variables prefaced
with BPANEL_
. Read more about configuring bPanel here.
With Docker
From inside the project directory in your terminal, run:
npm install && docker-compose up -d
This will start up three docker containers as detached processes running in the background.
Once everything has started up, you should be able to see your bPanel instance
at localhost:5000
. Note that this can take several minutes as bcoin and bcrypto build
inside the docker container. Use the docker logs
command to see the logs and check on
progress in your container.
Read more about how to connect a local instance of bPanel to a bcoin node running in docker here.
Managing Plugins
Plugin management is handled in a config.js
file located by default in the .bpanel
directory in your
system's home directory (this location can be manually changed with the BPANEL_PREFIX
env variable or
--prefix
option at run time.
bPanel comes pre-installed with a default theme called Genesis Theme
that bundles together a set of useful starter plugins and a custom skin called bMenace.
If you want, you can disable the Genesis Theme by removing it from the list in config.js
,
but if you want to keep using some of the plugins from the theme, feel free to add
them individually to your config!
Installing Plugins
To install plugins, simply add the name as a string to the plugins
array in ~/.bpanel/config.js
.
Make sure to match the name to the package name on npm
(localPlugins
can be used for plugins you are developing in the plugins/local
directory).
Once you save the file, bPanel will automatically install the plugins and rebuild.
For example:
// ~/.bpanel/config.js
export const localPlugins = ['my-local-plugin'];
export const plugins = ['@bpanel/genesis-theme', 'my-plugin'];
export default { localPlugins, plugins };
Note that if you have several plugins or themes being loaded,
this can take around 30 seconds as npm install
is run for you.
Discover all the plugins available by running npm search bpanel
in your console.
Configuration
bPanel can be configured to connect to any bcoin-API compatible node you want to
point it to, not just the docker container created by the default
docker-compose.yml
configurations.
Since bPanel just uses bclient
to connect
to and query nodes, all you need to do is pass the appropriate congifurations when starting up
bPanel. This can be done via the command line, environment variables (prefaced with BPANEL_
),
or through a configuration file. Under the hood, bPanel uses the bcfg
module
to accomplish this. (Learn more about bcfg
here)
bPanel looks for configuration files in your home directory in a .bpanel
folder
(~/.bpanel
) by default but this can be changed by passing a prefix
argument at runtime.
Client configurations for connecting to different nodes are loaded from the clients
directory, ~/.bpanel/clients/[CLIENT-ID].conf
.
You can have as many different configurations as you want. bPanel will default to a default.conf
configuration. To use different configurations, just pass in a client-id
argument at runtime.
e.g. npm start -- --client-id=test
(or as an env variable BPANEL_CLIENT_ID=test
) which
will load configs from ~/.bpanel/clients/test.conf
.
The clients directory can also be customized with the clients-dir
argument.
A sample conf file for the clients can be found here.
Since node and wallet services are run on different servers,
you will likely need different configurations to connect to the wallet. These
should be in the same client conf file, prefaced with wallet-
(note that bcoin looks for these
in separate config files but for bPanel clients we keep them together).
See the sample conf file for an example.
To directly serve bpanel over https without the reverse proxy, set the environment variables:
BPANEL_HTTPS=true
BPANEL_TLS_KEY=<path to key>
BPANEL_TLS_CERT=<path to cert>
About the Docker Environment
The default configs in the standard docker-compose.yml
file
bring up three separate services:
securityc
- TLS terminating reverse proxybpanel
- bPanel routing + static file server (connecting to the regtest node)bcoin
- bcoin bitcoin node/wallet (running a regtest node)
(Some plugins require TLS to function properly e.g. for hardware signing support).
The bpanel
service is an http server that acts as a static file server and as a request router
to backend services as well as a webpack process for building your JavaScript files.
The bcoin
service is an instance of bcoin
that supports an http
server, a wallet + bmultisig server and a bitcoin p2p server.
The securityc
service generates TLS keys and certs and runs a TLS terminating reverse proxy.
You can use custom configs to connect to an existing node,
or use the bcoin docker service to spin up a bcoin node that the webapp will connect to.
Learn more about the architecture of bPanel and related services at our website.
Configuration between Docker services
These instructions are for if you want to run bPanel within the bpanel
service and have it talk to
a bcoin node running in a container from the bcoin
service. This is how, for example, bPanel works
out of the box if you simply run docker-compose up -d
.
Configurations are shared between the two docker containers using a shared
docker volume called configs
. Settings for the bcoin nodes in docker
are set using environment variables, either in docker-compose.yml or
an env file (by default in ./etc/regtest.bcoin.env
but you can point to whichever and
as many env files as you want using the env_file
configuration in the bcoin
service). The bcoin node is started with the bcoin-init.js
script. During this
process, API keys are generated and all required configurations are saved in a config
file called _docker.conf
in the shared volume.
Local bPanel Dev (non-docker) with bcoin docker service
If the configs volume is mounted and mapped to your host machine, you can connect a local
version of bPanel to it by pointing the client-id
config at _docker
and it will
use the appropriate configs.
For local development, you run just the bcoin docker container (docker-compose up -d bcoin
)
and then npm run start:dev -- --client-id=_docker
(or npm run start:poll -- --client-id=_docker
on Mac to enbable webpack's watch with filesystem polling) to run bPanel and its server
from your local box.
Note that the --client-id
argument tells bPanel which client config
you want to use. _docker
is the name of the config automatically created by the bcoin
service.
If you are mounting a local bcoin data dir (~/.bcoin
) or persisting using docker volumes,
you can also pass settings to your bcoin docker container with a bcoin.conf
file (read more about bcoin configurations
here).
Bcoin Setup Scripts
(This section is only relevant if you will be running a bcoin node in a docker container
using the bcoin
service, or using the bcoin-init.js
script to start a node.)
This setup supports setup scripts for your bcoin node. This will allow you to run scripts on your node for a repeatable and predictable environment for testing or development.
Three circumstances need to be met to run a script:
- There needs to be a js file to run in the
scripts
directory that exports a function - You need to pass the name of this file (including the extension)
as an environment variable named
BCOIN_INIT_SCRIPT
in the docker-compose or as ainit-script
setting in yourbcoin.conf
file - There should be no walletdb in the container. This last requirement makes sure that a setup script doesn't overwrite your data if you're mapping volumes or if you restart a container.
These checks are done in bcoin-init.js
which is run by the bpanel/bcoin image
that is used to create the bcoin
container and sets up a node based on the configs
described above. Setup scripts are passed the bcoin node object that has been
created so the scripts have access to the node being started at run time as
well as the relevant configs.
Example setup scripts can be found in the /scripts
directory (funded-dummy-wallets.js
and setup-coinbase-address.js
).
Persistent DBs
By default, the bcoin and wallet DBs persist in the bcoin
docker volume.
If you want docker to start bcoin with a fresh DB, comment out the bcoin
volume in docker-compose.yml
then run docker-compose up -d
. Alternatively, you
can also persist your bcoin data within the named bcoin
volume or on the host machine.
Building local images
Uncomment the relevant build:
sections in docker-compose.yml
for the services you want to build, then run docker-compose build
Extending bPanel
The bPanel UI is built entirely around plugins. All visual elements can be extended or overridden via the plugin system including the header, footer, sidebar, and main panel/view element. To get started making your own plugin, use the bPanel-cli
Server extensions
The simplest thing to do, is to create your own server file that includes server/index.js
.
const bpanel = require('bpanel')({
network: 'main' // Put bPanel configs here (optional)
});
const app = require('express')();
app.use(/* Put your own middleware here */);
app.use(bpanel.app);
app.listen(5000);
Troubleshooting & FAQ
Nodejs Memory
With the availability of the bcoin, bcash, and hsd libraries, the webpack build process
requires an above average amount of memory available. To avoid JS Heap overflows, the
npm scripts that run webpack (start
, start:dev
, and start:poll
) pass an argument
--max_old_space_size
to increase the memory allocation. This can be adjusted as necessary.
Release Checklist
The following conditions must be tested before deploying a release. If any of the following circumstances causes a break, CHANGELOG should indicate a workaround or migration steps.
- [ ] Pull most recent version of
development
branch into an existing environment- [ ] Try a simple restart of the server (
npm run start
) - [ ] Try with a fresh
node_modules
(i.e.rm -rf node_modules && npm i
) - [ ] Try with a fresh configs (usually
~/.bpanel
) directory (renaming existing one and runningnpm install
will generate a fresh configs directory) - [ ] Install and uninstall new remote plugins using bpanel-cli
- [ ] Install and uninstall new local plugins using bpanel-cli
- [ ] Try a simple restart of the server (
- [ ] Download zip of development branch from GitHub (this emulates downloading a release from the website).
Test the following in a fresh environment (i.e. with no existing ~/.bpanel or other configs)
- [ ] Run
npm install
and confirm it creates a new ~/.bpanel directory withconfigs/
,configs.js
, andlocal_plugins
- [ ] Run
docker-compose up
and confirm after build is complete that bPanel is accessible atlocalhost:5000
- [ ] Confirm fresh install comes with the correct default plugins
- [ ] If docker-compose is set to mount config volume, confirm that installing and uninstalling plugins with bpanel-cli works as expected
- [ ] Bring down docker (
docker-compose down
) and test on host machine:npm run start
. This can be done against a docker node with the_docker.conf
client config or by passing in a customclient-id
at run time
- [ ] Run
- [ ] Test environments above with some of the most common plugins: e.g. recent-blocks, simple-wallet, simple-miner, etc.
- [ ] Bonus: check against different chain backends (e.g. handshake and bitcoin)
(Note that sometimes in order to check docker setup, you may have to build a new image from your
local Dockerfile. If uncommenting the build
lines in docker-compose, make sure to re-comment, before
comitting the change).
Once the above has been confirmed, commit the latest state of development to master as a new release, tag it with a new version, and publish to npm. bPanel follows Semantic Versioning rules.
TODO: Setup CI to accomplish as much of the above as possible.
License
- Copyright (c) 2018, The bPanel Devs (MIT License).