An open source block explorer for the B&C Exchange network. For more information about the B&C Exchange network visit http://bcexchange.org
A block explorer is an application that sorts and displays information regarding a blockchain(s). So things like
- block data
- transaction data
- address data
- motion and custodian data.
- network status
- network statistics
Before we get into setup and installation, let's layout the requirements and tools/frameworks used in this project.
- B&C Exchange Client
- Python (2.7)
- NPM (2.x)
- NodeJS (4.x)
- PostgreSQL (>=9.4)
- ExpressJS (>=4.x)
- AngularJS (>=1.4.3)
- Sass
- Grunt
Defined in requirements.txt
Before you start with the setup, make sure you have installed all the required tools (B&C Exchange Client, Python, NPM, NodeJS, PostgreSQL, Sass, Grunt, Virtualenv)
On Linux systems it is advised to run the software as a non-root user.
Create a new user with the sudo adduser bcex
command and answering the questions.
(bcex
is specified as a user name here as that is used in config files later in these instructions.
If you want to use a different user name, you will need to change some file paths later on to reflect the change)
Once you have your user created you can switch to that user with
$ sudo -u bcex -i
Next step is to clone and compile this repo.
git clone https://github.com/JetJet13/BCExplorer_OS.git
cd ./BCExplorer_OS
# Depending on your OS
npm install # Windows Users
sudo npm install # Linux Users
After you have installed PostgreSQL (>=9.4) the first thing we are going to do is create a database.
Open Windows Powershell
and navigate to your PostgreSQL bin
folder to start up psql.exe
> cd "C:\Program Files\PostgreSQL\{version}\bin"`
> ./psql
When it starts up, you should be connected with a user with superadmin privileges postgres
Now, you need to create a database called bcexchange
CREATE DATABASE bcexchange;
Once complete, you can either exit \q
or create a user with full privileges to bcexchange
To create a user will full privileges to the bcexchange
database,
CREATE USER ENTER_USERNAME WITH PASSWORD 'ENTER_PASSWORD';
GRANT ALL PRIVILEGES ON DATABASE "bcexchange" to ENTER_USERNAME;
\q # to exit
If you want to connect to the database through psql with the new user, you can use
> ./psql -d bcexchange -U ENTER_USERNAME
When you install PostgreSQL on Linux, it creates a user called postgres
,
so let's use the newly created user to access psql.
$ sudo su - postgres
$ psql
Now, you need to create a database called bcexchange
CREATE DATABASE bcexchange;
Once complete, you can either exit \q
or create a user with full privileges to bcexchange
To create a user will full privileges to the bcexchange
database,
CREATE USER ENTER_USERNAME WITH PASSWORD 'ENTER_PASSWORD';
GRANT ALL PRIVILEGES ON DATABASE "bcexchange" to ENTER_USERNAME;
\q # to exit
If you want to connect to the database through psql
with the new user, you can use
$ ./psql -d bcexchange -U ENTER_USERNAME
We will install Python dependencies to a virtualenv in the root of the BCExplorer_OS directory.
Run the following commands as the bcex
user
$ cd BCExplorer_OS
$ virtualenv ve
Then you can install the python dependencies into the virtualenv
$ ve/bin/pip install -r requirements.txt
Instructions to follow
Make sure to download, unzip and install (if your on windows) the B&C Exchange Client before starting this setup.
We need to create a configuration file for the client, so that we can connect to the client and make rpc requests.
Navigate to C:\Users\{username}\AppData\Roaming\BCExchange
. Note that AppData may be hidden.
Create and save a text file bcexchange.conf
. If you get a prompt, click yes.
Open the empty file with Notepad and paste in the following
rpcport=2240
rpcuser=<ENTER_USERNAME>
rpcpassword=<ENTER_PASSWORD>
server=1
Set rpcuser
and rpcpassword
to whatever you like and then save and exit.
Now, we want to start up the client, so navigate to where you downloaded and unzipped the folder and double-click either
bcexchange.exe
or bcexchanged.exe
# non-root user
$ cd /home/bcex/.bcexchange/
# then
$ sudo pico bcexchange.conf
Paste in the following
rpcport=2240
rpcuser=<ENTER_USERNAME>
rpcpassword=<ENTER_PASSWORD>
server=1
Set rpcuser
and rpcpassword
to whatever you like and then save and exit.
For this part of the setup, we are going to edit some source files to match the settings you created earlier, specifically
- bin/www
- public/api/api_tools.js
Open up these files and replace
Open the settings.yaml file and fill in the details. This file will be used by all the files in pyScripts
for connection to RPC
and Postgres
daemon_rpc:
username: <ENTER_RPC_USERNAME>
password: <ENTER_RPC_PASSWORD>
database:
database_name: bcexchange
username: <ENTER_DATABASE_USERNAME>
password: <ENTER_DATABASE_PASSWORD>
Next open /pyScripts/BC_parser.py
and /pyScripts/BC_insert.py
and make the following changes
First you have to comment out or delete lines.
Then you have to uncomment lines
After you have done these two steps to both files, they should both look like this
# Linux Users
# blk01 = "/root/.bcexchange/blk0001.dat"
# blk02 = "/root/.bcexchange/blk0002.dat"
# blk = ""
# Windows Users
blk01 = "C:/users/{username}/appdata/roaming/bcexchange/blk0001.dat"
blk02 = "C:/users/{username}/appdata/roaming/bcexchange/blk0002.dat"
blk = ""
The only thing you have to do to both files is make sure that lines
are pointing to the right folder, that is, if you are on root
user, then you don't have to make any changes.
Otherwise, replace /root
with /home/{username}
The next thing we have to do is run a python script that will create all the tables and triggers necessary for the explorer to work.
Make sure that the B&C Exchange Client is running before you start the script
> python /{folder-location}/BCExplorer_OS/pyScripts/PostgresSetup.py
$ sudo -u bcex -i
$ cd BCExplorer_OS
$ ve/bin/python pyScripts/PostgresSetup.py
Once complete, you are ready to start inserting data into the database
To insert data into the database, make sure that you successfully completed the sections Database Schema
and Edit Source Files
Make sure that the B&C Exchange Client is running before you start the script
> python /{folder-location}/BCExplorer_OS/pyScripts/BC_insert.py
Run this as the bcex
user and from the /home/bcex/BCExplorer_OS
directory
$ ve/bin/python pyScripts/BC_insert.py
Only launch the explorer if you have inserted data into the database. Otherwise you will get errors.
> cd /{folder-location}/BCExplorer_OS
> grunt server
Visit localhost:80
to view the application.
If you get an error:
DEPRECATION WARNING:
Sass 3.5 will no longer support Ruby 1.9.3.
Please upgrade to Ruby 2.0.0 or greater as soon as possible.
The explorer will still work fine, but if you want to fix it, visit this post
If there are any other errors in which you cannot fix, raise an issue in this repo and I'll try my best to help you.
We will set up supervisor
to manage the processes that need to run for the exchange.
We will also set up Nginx
to act as a reverse proxy and manage the web requests.
These need to be installed and run by a user with sudo
capabilities.
The instructions below are for Debian based systems (Ubuntu, Mint etc.), on other systems the package names and file paths may differ.
The supplied config files will work for the setup with the bcex
user as described above.
If you have used a different username or installed code to different paths, you will need to alter the conf files accordingly.
First you need to install both applications.
$ sudo apt-get install nginx supervisor
Copy the conf files found in <this repo>/confs/supervisor
to /etc/supervisor/conf.d
.
Then run
$ sudo service supervisor start
$ sudo supervisorctl update
This will start the supervisor manage and the managed programs defined in the conf files.
You can check on the status with the following command:
$ sudo supervisorctl status
This will show you the current state of the managed program. Log files created by the managed programs will be saved to the bcex
users home directory as defined in the conf files.
Open the <this_repo>/confs/nginx/explorer.conf
file and replace <server_name>
with the domain name you will use to reach the block explorer.
Copy that file to /etc/nginx/conf.d/explorer.conf
.
Run
$ sudo nginx -t
and ensure that there are no reported errors. If everything is reported successfully, restart nginx with
$ sudo service nginx restart
To add a bit more protection to the server you can set up some simple firewall rules.
$ sudo apt-get install ufw
$ sudo ufw allow ssh
$ sudo ufw allow http
$ sudo ufw enable
You should now be able to reach the block explorer on your domain. I would recommend enabling SSL and obtaining a certificate through LetsEncrypt but that is beyond the scope of this README.
Setup requires you to work in the order in which the sections are layed out. Skipping over some sections will only give you problems.
If you plan on using this in production, public API's come built-in, so you will need to edit the file /public/html/apis.html
Specifically, you will have to find and replace all YOUR_DOMAIN
snippets with the domain of your site.
ie) YOUR_DOMAIN/api/v1/block/3000
=> https://bcblockexplorer.com/api/v1/block/3000
If you have any questions/issues or feedback, please do not hesitate to raise an issue in this repo, or leave a message in the chat room.
Best of Luck
The MIT License (MIT)
Copyright (c) 2016 Johny Georges
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.