In my previous post I explained what the Bitcoin Core is and how to install it from Ubuntu repository. That was the easy way. If you are a developer you might be more interested in installing it by compiling the Bitcoin Core source code.
You may wonder why you’d want to make your life a bit more difficult by going through the complex process of compiling instead of just using precompiled binaries, which you can get easily with one command line? There are 3 reasons for that. The main reason is the latest releases. If you want to write cutting-edge bitcoin applications, it is a good idea to always have all the latest changes guys from Bitcoin Core came up with. The second reason is security. Compiling increases security because you don’t rely on pre-compiled binaries you can’t extract a source code from (so you can’t be certain they will do what they are supposed to). Compiling gives you an opportunity to inspect the source code which can make you certain what your new program will do. Obviously, with bitcoin this is only l’art pour l’art (art for art’s sake) because binaries from Bitcoin Core are very secure and reliable. Actually, the Bitcoin core guys set an example for an open source world by using Gitian. Without going into to much detail how it works, before a new binary is uploaded, first it is compiled by different developers and then cross-checked in a Gitian environment to make sure that it wasn’t compromised at any point). That last reason is more options. During the
./configure stage you have an ability to set different flags, for instance,
--without-guiif you don’t want GUI or
--disable-wallet if you don’t want your Bitcoin Core Node to serve as a wallet.
Bottom line is: if you are a developer you should compile the Bitcoin Core source code. You will learn about the underlying infrastructure better and maybe even some fun along the way. I’ve divided the compiling process into 4 steps:
- Installing git and downloading the Bitcoin Core source code.
- Configuring the Bitcoin Core Build by (commands:
- Compiling the source code and install the Bitcoin Core (command
sudo make install).
- Configuring our brand-new Bitcoin node and starting it.
Bitcoind vs bitcoin-qt – Bitcoind is a command-line bitcoin client that implements the Bitcoin Protocol for remote procedure call use. Bitcoin-qt on top of that provides a graphical user intarface (GUI). Both are completely compatible and oparates on the same data so you can easily switch beetwen them although they can’t run at the same time.
1. Cloning bitcoin repository
Before we start compiling anything first we need to get some source code. Bitcoin Core Project is hosted on the GitHub under the address: https://github.com/bitcoin/bitcoin. The version control used by GitHub – as you probably could’ve guessed it – is Git. By default, Git doesn’t come with Ubuntu 16.04 so our first step is to download and then install it.
Git – the most popular version control I probably don’t need to introduce to any developer. If you don’t feel completely confident with using the git commands, I can recommend a really awesome interactive tutorial – link. Having a good grasp on the Git commands is not neccessery to proceed with this tutorial but it will help you tremendeously with developing any project.
1a. Install git from repositories
$ sudo apt-get update $ sudo apt-get install git
1b. Get the source code by cloning it to your local git repository
By default, it should copy the source code to the newly created bitcoin folder in your $HOME directory.
$ git clone https://github.com/bitcoin/bitcoin.git
1c. Choosing version to compile
Once cloning is done you have a complete local copy of the Bitcoin source code in
~/bitcoin folder. Now, let’s go there by
cd command. source code versions are marked by a keyword tag. In the Bitcoin source code there are 2 types of version (doesn’t type of version sound kind of cool?) :
- with the rc suffix (rc – release candidates, which are intended for testing)
- without any suffix (which are stable versions).
You can display all versions by typing
git tag. By default, the local copy is synchronized with the most recent version which may be unstable (with rc suffix). I suggest you should choose the latest stable version which at the time of writing was v.0.15.1. To change which version our local git repository should point to we will use
$ cd bitcoin $ git tag $ git checkout v0.15.1
2. Configure the Bitcoin Core Build
The most annoying thing then compiling any UNIX program are the requirements of additional libraries (dependencies). If you don’t believe me check out dependency hell. But don’t worry, I’ll give you set-by-step instructions how to install all of them. If won’t have all the required libraries the building process simply fails letting you which one you are still missing. First, let’s read the Bitcoin Core guy’s welcoming message.
2a. Review the main documentation (in bitcoin folder)
$ more README.md
2b. Review the compiling instruction
Now, lets read the instructions for installing the Bitcoin Core on Unix system.
$ more doc/build-unix.md
If you are installing version later than v0.15.1 make sure if you don’t need any additional library apart from those from the following section.
2c. Install libraries required for building and compiling
$ sudo apt-get install build-essential libtool autotools-dev automake pkg-config libssl-dev libevent-dev bsdmainutils python3
2d. Install Boost Libraries
If you are really storage-constrained you can only install specific libraries listed in documentation but sometimes it is not enough so I would suggest installing the whole package (it is only around 270mb anyway).
$ sudo apt-get install libboost-all-dev
2e. Install BerkeleyDB
The Berkeley DB is a quick embedded database created by Oracle Corp, which is tightly integrated with Bitcoin Core Software. The problem is that Bitcoin Core uses the old 4.8.30 version. Why cannot it upgrade? Because newer versions produce non-backward compatible wallet files (
wallet.dat so they cannot be used by the previous versions of BerkleyDB. If you don’t care about it you can skip this step and pass
--with-incompatible-bdb during ./configure step.
$ sudo apt-get install software-properties-common $ sudo add-apt-repository ppa:bitcoin/bitcoin $ sudo apt-get update $ sudo apt-get install libdb4.8-dev libdb4.8++-dev
2.f Installing GUI libraries
If you wouldn’t like to have Bitcoin-Qt alongside with bitcoind you should pass the
--without-gui flag when ./configure. Nonetheless, I’d suggest installing GUI – it doesn’t do any harm (only 50mb package) and as saying goes – one cannot live by terminal alone 🙂
$ sudo apt-get install libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev qttools5-dev-tools libprotobuf-dev protobuf-compiler
The autogen.sh creates set of automatic scripts which will tell you whether your system has all the required libraries to compile the code. The most important of these is the configure which we will use in our next step for creating customized build scripts.
Moment of truth whether you’ve installed all the required libraries. Now is also the time to use different flags if you want to have customized compilation. You can see all of them by typing
./configure --help command. If you’ve decided that you want to have:
– the latest version of BerkeleyDB – use
– no GUI – use
– different than default installation location (
/usr/local/), for instance $HOME – use – -prefix=$HOME.
If everything goes well you will have the configured building scripts which we will use to finally compile Bitcoin Core source code.
3a. Compiling the source code
Compiling process may take a while until completed (even up to an hour) so take a break and grab a cup of coffee.
If the compilation process ends without any errors, the Bitcoin Core source code is compiled and executables files are created. Now we are ready for the installation.
3b. Installing Bitcoin Core
Using the executable created in the previous step we can install Bitcoin Core (mind that it requires administrator privileges so don’t forget sudo).
$ sudo make install
4 Setting up and running our full node
4a. Set up config file
Before we run our bitcoin node we should set up a password for the JSON-RPC interface which we will use to access the Bitcoin Core API. By deafult all the bitcoin data is stored in ~/.bitcoin folder (Warning! Don’t confuse .bitcoin with bitcoin – the bitcoin folder stores only the Bitcoin Core source code we cloned and our compiled executables we used to install Bitcoin Core). Go then to the .bitcoin folder and create new file
$ cd ~/.bitcoin $ nano bitcoin.conf
Nano is a simple UNIX text editor we will use to create a new configuration file in which we will specify our rpcuser name and rpcpassword. Type these two lines (remember to change the given values):
Let’s have a look at different options you can set in your configuration file. To list all of them you can use this line
bitcoind --help. The most interesting ones:
datadir– setting the directory where the blockchain will be downloaded. Make sure it has at least 200gigabytes of free memory. By default, it downloaded to
prune– full blockchain might hefty, as of now (Jan 2018) it takes over 160gigs to store it. If you don’t have enough space on your disk or you are simply storage stingy you can set this parameter which will force your node to delete old blocks. A value it takes is a number of blocks you want to store it. By default, it is set to 0 which means all blocks are going to be stored. The minimum value (apart from 0) is 550, which will make your node store 550 newest blocks – since a new block is mined every 10 minutes that will give you blocks from the last 2days. You can set this number higher if you want but the minimum for your node to work properly is 550. It won’t be a full node but will keep the capabilities to validate transactions.
txindex– by default only your transactions are indexed meaning your Bitcoin Core’s database will store hashes of only your transactions. There is a cool Bitcoin Core command getrawtransaction which takes a transaction id as parameter and return all information about the transaction. For developers I would recommend setting this option to 1 (storing hashes for all transactions). If you already downloaded the blockchain without it but now want full indexing, after setting this option you need to restart your Bitcoin Core with -reindex option.
Our final configuration file may look like that:
rpcuser=user_name rpcpassword=your_rpc_password txindex=1 prune=550 //only if you really don't have the space for the whole blockchain
We save our file by pressing ctrl+o. Our configuration file is ready. By pressing ctrl+e we are going back to the terminal window.
4a. Running your bitcoin node
As I mentioned before there are two ways of running your full node: with
bitcoin-qt which will give your graphical user interface or with
bitcoind which will give you only command-line interface (CLI). For the first time I suggest running the GUI version:
It will show you a Bitcoin Core window showing you how much of the blockchain you still need to download and how long it will take.
It might be a good idea to start Bitcoin Core on a startup. To do that you need to go to settings, and tick the correct box:
The last thing you would like to check out is the debug window. Here you can see the general information of your node, like Bitcoin Core version or the current number of blocks in the bitcoin blockchain. You can also take a look how many other nodes are connected to you (in Peers panel) or start exploring the blockchain using the console. If you are interested in doing so – in my next article I will cover the most useful
bitcoin-cli options enabling surfing the bitcoin blockchain and also give you a simple example how to use bitcoin-cli programmatically – by using Bitcoin Core API.