{"id":23109207,"url":"https://github.com/bpanel-org/bpanel","last_synced_at":"2025-08-16T18:32:14.937Z","repository":{"id":53653406,"uuid":"127349359","full_name":"bpanel-org/bpanel","owner":"bpanel-org","description":"A Blockchain Management System, powered by bcoin","archived":false,"fork":false,"pushed_at":"2020-01-11T00:35:34.000Z","size":4493,"stargazers_count":53,"open_issues_count":12,"forks_count":23,"subscribers_count":14,"default_branch":"development","last_synced_at":"2024-10-07T09:06:03.707Z","etag":null,"topics":["bcoin","bitcoin","blockchain","bpanel","webapp"],"latest_commit_sha":null,"homepage":"https://bpanel.org","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bpanel-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"securityc.env","support":null}},"created_at":"2018-03-29T21:29:15.000Z","updated_at":"2024-04-09T03:35:17.000Z","dependencies_parsed_at":"2022-09-16T07:41:07.047Z","dependency_job_id":null,"html_url":"https://github.com/bpanel-org/bpanel","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpanel-org%2Fbpanel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpanel-org%2Fbpanel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpanel-org%2Fbpanel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpanel-org%2Fbpanel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bpanel-org","download_url":"https://codeload.github.com/bpanel-org/bpanel/tar.gz/refs/heads/development","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230048744,"owners_count":18164799,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bcoin","bitcoin","blockchain","bpanel","webapp"],"created_at":"2024-12-17T01:34:13.777Z","updated_at":"2024-12-17T01:34:14.618Z","avatar_url":"https://github.com/bpanel-org.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Welcome to bPanel!\n\nThis is the official repo for the [bPanel project](https://bpanel.org),\na full featured, enterprise level GUI for your bcoin Bitcoin node.\n\nFor complete developer and API documentation, visit our website: https://bpanel.org\n\n## Table of Contents\n\n- [Dependencies](#dependencies)\n- [Quick Start](#quick-start)\n  - [Quick Start w/ existing node](#with-an-existing-node)\n  - [Quick Start (w/ Docker)](#with-docker)\n- [Managing Plugins](#managing-plugins)\n- [Configuration](#configuration)\n- [About the Docker Environment](#about-the-docker-environment)\n- [Logging](#logging)\n- [Extending bPanel](#extending-bpanel)\n- [Troubleshooting \u0026 FAQ](#troubleshooting--faq)\n## Dependencies\n\n- npm \u003e= 5.7.1\n- node \u003e= 8.9.4\n\nNOTE: It is important to be using at least this version of `npm`\nbecause of a bug that removes `node_modules` that are installed from\nGitHub and doesn't reinstall them which breaks the build.\n\n## Quick Start\n\n```bash\nnpm install\nnpm start\n```\n\nYou can add configurations for your node with the\n[Connection Manager plugin](https://github.com/bpanel-org/connection-manager).\n\nRead more about configuring bPanel and nodes you would like\nto interface with [here](#configuration).\n\n### With Docker\n\nFrom inside the project directory in your terminal, run:\n\n```bash\nnpm install \u0026\u0026 docker-compose up -d\n```\n\nThis will start up three docker containers as [detached processes running in the background](https://docs.docker.com/compose/reference/up/).\nOnce everything has started up, you should be able to see your bPanel instance\nat `localhost:5000`. Note that this can take several minutes as bcoin and bcrypto build\ninside the docker container. Use the `docker logs` command to see the logs and check on\nprogress in your container.\n\nRead more about how to connect a local instance of bPanel to a bcoin node running in docker\n[here](#local-bpanel-dev-using-bcoin-docker-container).\n\n#### Plugins with Docker Compose\nIt's possible to set which plugins you want loaded via an environment variable `BPANEL_PLUGINS`.\nThe docker compose has this set for you and can be customized according to your needs.\nNote however that once set, they cannot be edited using the methods listed\n[below](#managing-plugins). To make changes, you will need to edit `docker-compose.yml` and\nrestart the container. Comment out this environment variable to use the config.js instead.\n\n## Managing Plugins\n\nPlugin management is handled in a `config.js` file located by default in the `.bpanel` directory in your\nsystem's home directory (this location can be manually changed with the `BPANEL_PREFIX` env variable or\n`--prefix` option at run time.\n\nbPanel comes pre-installed with a default theme called [`Genesis Theme`](https://github.com/bpanel-org/genesis-theme)\nthat bundles together a set of useful starter plugins and a custom skin called [bMenace](https://github.com/bpanel-org/bmenace-theme).\nIf you want, you can disable the Genesis Theme by removing it from the list in `config.js`,\nbut if you want to keep using _some_ of the plugins from the theme, feel free to add\nthem individually to your config!\n\n### Installing Plugins\n\nTo install plugins, simply add the name as a string to the `plugins` array in `~/.bpanel/config.js`.\nMake sure to match the name to the package name on npm\n(`localPlugins` can be used for plugins you are developing in the `plugins/local` directory).\nOnce you save the file, bPanel will automatically install the plugins and rebuild.\n\nFor example:\n\n```javascript\n// ~/.bpanel/config.js\nexport const localPlugins = ['my-local-plugin'];\n\nexport const plugins = ['@bpanel/genesis-theme', 'my-plugin'];\n\nexport default { localPlugins, plugins };\n```\n\nNote that if you have several plugins or themes being loaded,\nthis can take around 30 seconds as `npm install` is run for you.\n\nDiscover all the plugins available by running `npm search bpanel` in your console.\n\n## Configuration\n\nbPanel can be configured to connect to any bcoin-API compatible node you want to\npoint it to, not just the docker container created by the default\n`docker-compose.yml` configurations.\n\nSince bPanel just uses [`bclient`](https://github.com/bcoin-org/bclient) to connect\nto and query nodes, all you need to do is pass the appropriate congifurations when starting up\nbPanel. This can be done via the command line, environment variables (prefaced with `BPANEL_`),\nor through a configuration file. Under the hood, bPanel uses the `bcfg` module\nto accomplish this. (Learn more about `bcfg` [here](https://github.com/bcoin-org/bcfg))\n\nbPanel looks for configuration files in your home directory in a `.bpanel` folder\n(`~/.bpanel`) by default but this can be changed by passing a `prefix` argument at runtime.\nClient configurations for connecting to different nodes are loaded from the `clients`\ndirectory, `~/.bpanel/clients/[CLIENT-ID].conf`.\n\nYou can have as many different configurations as you want. bPanel will default to a `default.conf`\nconfiguration. To use different configurations, just pass in a `client-id` argument at runtime.\ne.g. `npm start -- --client-id=test` (or as an env variable `BPANEL_CLIENT_ID=test`) which\nwill load configs from `~/.bpanel/clients/test.conf`.\n\nThe clients directory can also be customized with the `clients-dir` argument.\n\nA sample conf file for the clients can be found\n[here](https://github.com/bpanel-org/bpanel/tree/master/etc/sample.client.conf).\n\nSince node and wallet services are run on different servers,\nyou will likely need different configurations to connect to the wallet. These\nshould be in the same client conf file, prefaced with `wallet-` (note that bcoin looks for these\nin separate config files but for bPanel clients we keep them together).\nSee the sample conf file for an example.\n\nTo directly serve bpanel over https without the reverse proxy, set the environment\nvariables:\n\n```bash\nBPANEL_HTTPS=true\nBPANEL_TLS_KEY=\u003cpath to key\u003e\nBPANEL_TLS_CERT=\u003cpath to cert\u003e\n```\n\nSome plugins require being served over `https`, such as plugins that use hardware wallets.\nThis is because WebUSB will not work by default on non `https` sites.\n\nTo generate a simple self signed certificate for development or local hosting, use the command:\n\n```bash\n$ openssl req -newkey rsa:2048 -nodes -sha512 -x509 -days 3650 -nodes -subj '/CN=localhost' -out selfsigned.crt -keyout selfsigned.key\n```\n\nDo not use this for production!\n\n## About the Docker Environment\n\nThe default configs in the standard `docker-compose.yml` file\nbring up three separate services:\n\n- `securityc` - TLS terminating reverse proxy\n- `bpanel` - bPanel routing + static file server (connecting to the regtest node)\n- `bcoin` - bcoin bitcoin node/wallet (running a regtest node)\n\n(Some plugins require TLS to function properly e.g. for hardware signing\nsupport).\n\nThe `bpanel` service is an http server that acts as a static file server and as a request router\nto backend services as well as a webpack process for building your JavaScript files.\nThe `bcoin` service is an instance of `bcoin` that supports an http\nserver, a wallet + [bmultisig](https://github.com/bcoin-org/bmultisig) server and a bitcoin p2p server.\n\nThe `securityc` service generates TLS keys and certs and runs a TLS terminating reverse proxy.\nYou can use custom configs to connect to an existing node,\nor use the bcoin docker service to spin up a bcoin node that the webapp will connect to.\n\nLearn more about the architecture of bPanel and related services [at our website](https://bpanel.org/docs/bpanel-overview.html#architecture).\n\n#### Configuration between Docker services\n\nThese instructions are for if you want to run bPanel within the `bpanel` service and have it talk to\na bcoin node running in a container from the `bcoin` service. This is how, for example, bPanel works\nout of the box if you simply run `docker-compose up -d`.\n\nConfigurations are shared between the two docker containers using a shared\ndocker volume called `configs`. Settings for the bcoin nodes in docker\nare set using environment variables, either in docker-compose.yml or\nan env file (by default in `./etc/regtest.bcoin.env` but you can point to whichever and\nas many env files as you want using the `env_file` configuration in the bcoin\nservice). The bcoin node is started with the `bcoin-init.js` script. During this\nprocess, API keys are generated and all required configurations are saved in a config\nfile called `_docker.conf` in the shared volume.\n\n#### Local bPanel Dev (non-docker) with bcoin docker service\n\nIf the configs volume is mounted and mapped to your host machine, you can connect a local\nversion of bPanel to it by pointing the `client-id` config at `_docker` and it will\nuse the appropriate configs.\n\nFor local development, you run just the bcoin docker container (`docker-compose up -d bcoin`)\nand then `npm run start:dev -- --client-id=_docker` (or `npm run start:poll -- --client-id=_docker`\non Mac to enbable webpack's watch with filesystem polling) to run bPanel and its server\nfrom your local box.\n\nNote that the `--client-id` argument tells bPanel which client config\nyou want to use. `_docker` is the name of the config automatically created by the bcoin\nservice.\n\nIf you are mounting a local bcoin data dir (`~/.bcoin`) or persisting using docker volumes,\nyou can also pass settings to your bcoin docker container with a `bcoin.conf`\nfile (read more about bcoin configurations\n[here](https://github.com/bcoin-org/bcoin/blob/master/docs/Configuration.md)).\n\n### Bcoin Setup Scripts\n\n(This section is only relevant if you will be running a bcoin node in a docker container\nusing the `bcoin` service, or using the `bcoin-init.js` script to start a node.)\n\nThis setup supports setup scripts for your bcoin node. This will allow you to run\nscripts on your node for a repeatable and predictable environment for testing or development.\n\nThree circumstances need to be met to run a script:\n\n1. There needs to be a js file to run in the `scripts` directory that exports a function\n1. You need to pass the name of this file (including the extension)\n   as an environment variable named `BCOIN_INIT_SCRIPT` in the docker-compose or as a\n   `init-script` setting in your `bcoin.conf` file\n1. There should be no walletdb in the container.\n   This last requirement makes sure that a setup script doesn't overwrite your data\n   if you're mapping volumes or if you restart a container.\n\nThese checks are done in `bcoin-init.js` which is run by the bpanel/bcoin image\nthat is used to create the `bcoin` container and sets up a node based on the configs\ndescribed above. Setup scripts are passed the bcoin node object that has been\ncreated so the scripts have access to the node being started at run time as\nwell as the relevant configs.\n\nExample setup scripts can be found in the `/scripts` directory (`funded-dummy-wallets.js`\nand `setup-coinbase-address.js`).\n\n### Persistent DBs\n\nBy default, the bcoin and wallet DBs persist in the `bcoin` docker volume.\nIf you want docker to start bcoin with a fresh DB, comment out the `bcoin`\nvolume in `docker-compose.yml` then run `docker-compose up -d`. Alternatively, you\ncan also persist your bcoin data within the named `bcoin` volume or on the host machine.\n\n### Building local images\n\nUncomment the relevant `build:` sections in `docker-compose.yml`\nfor the services you want to build, then run `docker-compose build`\n\n## Logging\nBy default, the bPanel server will log to your console and create a debug.log file in your\nprefix directory (defaults to `~/.bpanel`). The logger can be configured via command line\narguments, your `config.js`, environment variables (prefaced with `BPANEL_`). See\n[Configuration](#configuration) for more on setting bPanel configurations.\n\nbPanel uses the [blgr](https://github.com/bcoin-org/blgr/) module for logging.\nYou can set custom values for level, file, console, and shrink. All but level are\nboolean (true/false). Available options for level are: none, error, warning, info, debug, and spam.\nSee [blgr](https://github.com/bcoin-org/blgr/) for more info.\n\n## Extending bPanel\n\nThe bPanel UI is built entirely around plugins.\nAll visual elements can be extended or overridden via the plugin system\nincluding the header, footer, sidebar, and main panel/view element.\nTo get started making your own plugin, use the\n[bPanel-cli](http://bpanel.org/docs/plugin-started.html)\n\n### Server extensions\n\nThe simplest thing to do, is to create your own server file that includes `server/index.js`.\n\n```javascript\nconst bpanel = require('bpanel')({\n  network: 'main' // Put bPanel configs here (optional)\n});\nconst app = require('express')();\napp.use(/* Put your own middleware here */);\napp.use(bpanel.app);\napp.listen(5000);\n```\n\n## Troubleshooting \u0026 FAQ\n#### Nodejs Memory\nWith the availability of the bcoin, bcash, and hsd libraries, the webpack build process\nrequires an above average amount of memory available. To avoid JS Heap overflows, the\nnpm scripts that run webpack (`start`, `start:dev`, and `start:poll`) pass an argument\n`--max_old_space_size` to increase the memory allocation. This can be adjusted as necessary.\n\n#### NPM and NodeJS versions\nThere are some weird bugs in npm from early 2018 that would erase any modules installed\nfrom a GitHub repository when `npm install` is run a second time. If you are getting\nerrors about missing packages, make sure you have the right versions:\n\n- npm \u003e= 5.7.1\n- node \u003e= 8.9.4\n\n##### A note about the `$PATH` variable\nNote that bPanel will actually do a check of your system's `npm` version and the process's\nversion of node and will fail if these don't reach the minimum requirements. If you believe\nyou have the right version of `npm` installed, make sure it is in the `PATH` environment variable.\n\nYou can check this by running:\n\n```bash\n$ which npm\n# /usr/local/bin/npm\n```\n\nMake sure the returned path is included in the following return:\n```bash\n$ echo $PATH\n# /usr/local/bin:/usr/local/sbin:/usr/local/lib\n```\n\n\n## Release Checklist\nThe following conditions must be tested before deploying a release. If any of the following\ncircumstances causes a break, CHANGELOG should indicate a workaround or migration steps.\n\n- [ ] Pull most recent version of `development` branch into an existing environment\n  - [ ] Try a simple restart of the server (`npm run start`)\n  - [ ] Try with a fresh `node_modules` (i.e. `rm -rf node_modules \u0026\u0026 npm i`)\n  - [ ] Try with a fresh configs (usually `~/.bpanel`) directory (renaming existing one and\n  running `npm install` will generate a fresh configs directory)\n  - [ ] Install and uninstall new remote plugins using bpanel-cli\n  - [ ] Install and uninstall new local plugins using bpanel-cli\n- [ ] Download zip of development branch from GitHub (this emulates downloading a release from the website).\nTest the following in a fresh environment (i.e. with no existing ~/.bpanel or other configs)\n  - [ ] Run `npm install` and confirm it creates a new ~/.bpanel directory with `configs/`, `configs.js`,\n  and `local_plugins`\n  - [ ] Run `docker-compose up` and confirm after build is complete that bPanel is accessible at `localhost:5000`\n  - [ ] Confirm fresh install comes with the correct default plugins\n  - [ ] If docker-compose is set to mount config volume, confirm that installing and\n  uninstalling plugins with bpanel-cli works as expected\n  - [ ] Bring down docker (`docker-compose down`) and test on host machine: `npm run start`.\n  This can be done against a docker node with the `_docker.conf` client config or by passing\n  in a custom `client-id` at run time\n- [ ] Test environments above with some of the most common plugins: e.g. recent-blocks, simple-wallet,\n simple-miner, etc.\n- [ ] Bonus: check against different chain backends (e.g. handshake and bitcoin)\n\n(Note that sometimes in order to check docker setup, you may have to build a new image from your\nlocal Dockerfile. If uncommenting the `build` lines in docker-compose, make sure to re-comment, before\ncomitting the change).\n\nOnce the above has been confirmed, commit the latest state of development to master as a new release,\ntag it with a new version, and publish to npm. bPanel follows [Semantic Versioning](http://semver.org/) rules.\n\n_TODO: Setup CI to accomplish as much of the above as possible._\n\n## License\n\n- Copyright (c) 2018, The bPanel Devs (MIT License).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbpanel-org%2Fbpanel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbpanel-org%2Fbpanel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbpanel-org%2Fbpanel/lists"}