Skip to content

Building on Ubuntu 16.04 LTS

This document describes the installation of DCore on a fresh install of Ubuntu Server 16.04 LTS1

What is Ubuntu 16.04 LTS and why we are supporting it

Ubuntu 16.04 LTS is a Linux distribution that is intended for production server deployment. The 'LTS' designation indicates that it will receive "Long Term Support" for security fixes and critical bug fixes for a known period of time (five years from initial release, at time of writing) without the requirement to install a completely new version of the operating system, and all the server components every few months.

This long term support is one of the reason Decent has chosen Ubuntu 16.04 as one of its standard build targets.

More information on Ubuntu LTS and Long Term Support in general

Quick Start for Experts Only

💥 ALWAYS CHECK ALL PRECONDITIONS ARE MET since Nasty Things™ can happen if you don't do so 💥

This is a quick summary for IT professionals and technically experienced users only:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
# Change the following value if you wish to build in a different location.
export DEV_HOME=~/Projects/Decent

export THIRDPARTY_HOME=${DEV_HOME}/3rdParty
export ARCHIVE_HOME=${THIRDPARTY_HOME}/ZArchives

export BUILD_LOGS=${DEV_HOME}/Logs
export CURR_BUILD_LOGS=${BUILD_LOGS}/`date +"%Y-%m-%d_%H%m"`
export BUILD_CACHE_LOG=${CURR_BUILD_LOGS}/cmake-build-cache.log
export BUILD_ALL_LOG=${CURR_BUILD_LOGS}/cmake-build-all.log
export BUILD_INSTALL_LOG=${CURR_BUILD_LOGS}/cmake-install.log

mkdir --parents ${DEV_HOME}
mkdir --parents ${THIRDPARTY_HOME}
mkdir --parents ${ARCHIVE_HOME}
mkdir --parents ${CURR_BUILD_LOGS}

### Install pre-requisits using APT package manager
sudo apt-get update -qq 
sudo apt-get install -qq build-essential autotools-dev automake autoconf libtool make cmake checkinstall realpath gcc g++ clang flex bison doxygen gettext git qt5-default libqt5svg5-dev libreadline-dev libcrypto++-dev libgmp-dev libdb-dev libdb++-dev libssl-dev libncurses5-dev libboost-all-dev libcurl4-openssl-dev python-dev libicu-dev libbz2-dev

### Building CMake 3.7.2

export CMAKE_CONFIGURE_LOG=${CURR_BUILD_LOGS}/cmake-comfigure.log
export CMAKE_MAKE_LOG=${CURR_BUILD_LOGS}/cmake-make.log
export CMAKE_INSTALL_LOG=${CURR_BUILD_LOGS}/cmake-install.log

cd $ARCHIVE_HOME
wget https://cmake.org/files/v3.7/cmake-3.7.2.tar.gz

cd ${THIRDPARTY_HOME}
mkdir cmake
cd cmake
tar xf ${ARCHIVE_HOME}/cmake-3.7.2.tar.gz
mkdir cmake-3.7.2_prefix
cd cmake-3.7.2
export CMAKE_ROOT=$(realpath ../cmake-3.7.2_prefix)
./configure --prefix=$CMAKE_ROOT  |& tee ${CMAKE_CONFIGURE_LOG}
make |& tee ${CMAKE_MAKE_LOG}
make install |& tee ${CMAKE_INSTALL_LOG}
cd ${DEV_HOME}
export PATH=$CMAKE_ROOT/bin:$PATH

### Building Boost 1.60.0
export BOOST_BOOTSTRAP_LOG=${CURR_BUILD_LOGS}/boost-bootstrap.log
export BOOST_BUILD_LOG=${CURR_BUILD_LOGS}/boost-build.log

cd $ARCHIVE_HOME
wget https://sourceforge.net/projects/boost/files/boost/1.60.0/boost_1_60_0.tar.gz 

mkdir ${THIRDPARTY_HOME}/boost
cd ${THIRDPARTY_HOME}/boost
tar xf ${ARCHIVE_HOME}/boost_1_60_0.tar.gz
mkdir boost-1.60.0_prefix
cd boost_1_60_0
export BOOST_ROOT=$(realpath ../boost-1.60.0_prefix)

./bootstrap.sh --prefix=$BOOST_ROOT |& tee ${BOOST_BOOTSTRAP_LOG}
./b2 install  |& tee ${BOOST_BUILD_LOG}
cd ${DEV_HOME}

# Get and build DCore

cd ${DEV_HOME}
git clone https://github.com/DECENTfoundation/DECENT-Network
cd DECENT-Network
git submodule update --init --recursive
git checkout

export DECENT_NETWORK=${DEV_HOME}/DECENT-Network
export DECENT_BUILD=${DECENT_NETWORK}-build
mkdir ${DECENT_BUILD}

WALLET_CPP=${DECENT_NETWORK}/libraries/wallet/wallet.cpp
mv ${WALLET_CPP} ${WALLET_CPP}.COPY && sed -e "s/^\/\/\#define DECENTGO/\#define DECENTGO/" ${WALLET_CPP}.COPY > ${WALLET_CPP}

cd ${DECENT_BUILD}

cmake -G "Unix Makefiles" -D CMAKE_BUILD_TYPE=Debug ${DECENT_NETWORK} |& tee ${BUILD_CACHE_LOG}
cmake --build . --target all -- -j -l 3.0 |& tee ${BUILD_ALL_LOG}
cmake --build . --target install |& tee ${BUILD_INSTALL_LOG}

Preconditions

  • A fresh installation of Ubuntu Server 16.04 LTS 64 bit Server on either physical hardware, or a reliable Virtual Machine Hypervisor. Download an ISO DVD image directly from here2.
  • At least 6 GB RAM3.
  • 16 GB Hard Disk storage to allow for the primary drive and a 6 GB swap partition3.
  • A working Internet connection and access through any firewall to permit tools, such as wget and git to retrieve files from remote repositories.
  • a user with the name decent who is in the sudo group.
  • an initial login user who is a member of the sudo group who can initially configure the system.
Adding the decent user

This, like most of the instructions in this document, can only be done by a user with root priviledges. (Similar to Administrator rights in Windows)

After you have logged into your Ubuntu system and established that everything is functioning correctly, create the decent user with the following command:

sudo adduser decent
  1. The system will prompt you for a password for the decent user and will ask you to repeat it, as is usual with the passwd command.
  2. It will then prompt you to add user information. Filling in these fields is optional and each can be skipped by hitting the Enter key.
  3. You will finally be asked if this information is correct. Typing y will create the user and return you to the command prompt, while, n will ask you to re-enter the user information.

The next step is to make the decent user a member of the sudo5 group:

sudo usermod -aG sudo decent
should achieve this.

Issues you might encounter when using sudo

  1. If you don't put sudo before a root restricted command, you will get an error similar to this:

    $ useradd decent
    Command 'useradd' is available in '/usr/sbin/useradd'
    The command could not be located because '/usr/sbin' is not included in the PATH environment variable.
    This is most likely caused by the lack of administrative privileges associated with your user account.
    useradd: command not found
    
  2. Not having any administration privileges, or not being a member of the sudo group is the most likely cause of this error:

    $ usermod decent
    Command 'usermod' is available in '/usr/sbin/usermod'
    The command could not be located because '/usr/sbin' is not included in the PATH environment variable.
    This is most likely caused by the lack of administrative privileges associated with your user account.
    usermod: command not found
    
    Ensure you are logged in under an account with sudo privileges.

  3. The sudo manpage is a useful place to check if you still have problems.
Getting information and help on Linux commands

If you are having problems understanding a Linux command, such as adduser, you can use the built in manual pages (man pages) to find out more information.

Using the built in manpages

For example:

man adduser
or
man sudo

will display the manual pages for these commands. If your terminal is correctly set up5, the following keystrokes will help you navigate:

  • q to quit and go back to the command line.
  • h to show the help page (q to go back to the manual page).
  • Home to go to the start of the manual page.
  • end to go to the end of the manual page.
  • PgUp, or b to go back a page.
  • PgDown, or f to go forward a page.
Using Ubuntu's online manpages

Ubuntu's online help pages are available here.

Warnings and Suggestions

  1. These instructions are meant to be applied to a fresh installation of Ubuntu 16.04 LTS. Using them in any other situation has not been tested and will be at the user's own risk and discretion.

  2. Building a virtual machine using VirtualBox ( Official Oracle Site) is recommended .

  3. Choosing the SSH Server option when installing Ubuntu is useful since it will allow you to open more advanced terminals and transfer files from the host operating system (or other systmes, if required).

    Note that in this case you may need to set the $TERM environment variable to the correct value for the incoming terminal connection. (ie. for Cygwin, TERM=cygwin)

How to use these instructions

It is expected that anyone using these instructions already have some familiarity with Linux or Unix systems and be able to find their way around the filesystem using the command line.

For more experienced users, there is a section above ("Quick Start for Experts Only") which shows all the steps required to build the system without any descriptive text, or the extended logging files. This is for the impatient developer or systems administrator only.

For non-experts, the steps required to build the system are laid out and, in as much as makes sense, since this is not a programming tutorial, explained.

Read this documentation, in full, before you start anything and research anything that you might be unsure of. Web searches will provide many opportunities to learn how to use the command line and understand the Linux file system, for example.

While following the instructions, copy each line of the script and paste it into the command terminal before hitting Enter. Typing them yourself is more likely to lead to errors that may not be obvious to fix.

If problems arise even after double checking your work, check the Notes and Comments section of this document for possible fixes. We aim to update this on a regular basis in response to user experiences.

While we have thoroughly tested this script, both internally and externally, it is possible that some errors have escaped our scrutiny, or external factors we have not encountered ourselves might cause issues while building. In such cases, please contact Support.

Building Sources

These variables determine where the code will be built.

1
2
3
export DEV_HOME=~/Projects/Decent
export THIRDPARTY_HOME=${DEV_HOME}/3rdParty
export ARCHIVE_HOME=${THIRDPARTY_HOME}/ZArchives

  • $DEV_HOME - The DCore code will be downloaded and built under this directory
  • $THIRDPARTY_HOME - is where all 'Third Party' resources needed by the build system will be downloaded, and in most cases, built and installed.
  • $ARCHIVE_HOME - is where most third party archive files will be downloaded to, and stored.

The following commands create environment variables7 related to logging the the build process so it can be diagnosed should any problems occur.

4
5
6
7
8
export BUILD_LOGS=${DEV_HOME}/Logs
export CURR_BUILD_LOGS=${BUILD_LOGS}/`date +"%Y-%m-%d_%H%m"`
export BUILD_CACHE_LOG=${CURR_BUILD_LOGS}/cmake-build-cache.log
export BUILD_ALL_LOG=${CURR_BUILD_LOGS}/cmake-build-all.log
export BUILD_INSTALL_LOG=${CURR_BUILD_LOGS}/cmake-install.log

The first two variables determine the top level log file structure. Each time this script is followed, a new directory is created to store all log files related to that build.

To differentiate these builds, this directory is named with the time that the build began (to the nearest minute). Format is "Year-Month-Day_HoursMinutes"; ie: "2018-04-28_0532".

  • $BUILD_LOGS - The parent directory of all log files.
  • $CURR_BUILD_LOGS - the parent directory of all log files produced by a specific build run.

Next come the names of individual log files:

  • $BUILD_CACHE_LOG - Is the log for the cmake -G "Unix Makefiles" -D CMAKE_BUILD_TYPE=Debug ${DECENT_NETWORK} command
  • $BUILD_ALL_LOG - Is the log for the cmake --build . --target all -- -j -l 3.0 command.
  • $BUILD_INSTALL_LOG - Is the log for the cmake --build . --target install command.

Now create the directories:

 9
10
11
12
mkdir --parents ${DEV_HOME}
mkdir --parents ${THIRDPARTY_HOME}
mkdir --parents ${ARCHIVE_HOME}
mkdir --parents ${CURR_BUILD_LOGS}
This next step is the one most likely to cause damage to a production server

Installing and updating packages can create a situation where a non APT managed application might not be compatible with the changes made during the upgrade or installation. For this reason, caution must also be taken when using the apt-get upgrade command.

These commands update the APT package management database, then installs any missing pre-requisite packages. See the Ubuntu apt-get manpages for more information.

13
14
sudo apt-get update -qq 
sudo apt-get install -qq build-essential autotools-dev automake autoconf libtool make cmake checkinstall realpath gcc g++ clang flex bison doxygen gettext git qt5-default libqt5svg5-dev libreadline-dev libcrypto++-dev libgmp-dev libdb-dev libdb++-dev libssl-dev libncurses5-dev libboost-all-dev libcurl4-openssl-dev python-dev libicu-dev libbz2-dev

Building CMake 3.7.2

Because the build dependencies of DCore are complex and rely on having a compatible version of CMake installed, this build process ensures this by building a local version of CMake, then inserting it into the head of the $PATH environment variable.

First set up logging:

15
16
17
export CMAKE_CONFIGURE_LOG=${CURR_BUILD_LOGS}/cmake-comfigure.log
export CMAKE_MAKE_LOG=${CURR_BUILD_LOGS}/cmake-make.log
export CMAKE_INSTALL_LOG=${CURR_BUILD_LOGS}/cmake-install.log

Next download the source code archive file:

18
19
cd $ARCHIVE_HOME
wget https://cmake.org/files/v3.7/cmake-3.7.2.tar.gz
In the $THIRDPARTY_HOME directory, create the required sub-directories, unpack the archive and create an environment variable ($CMAKE_ROOT) that holds the location of the compiled utility and all its support files:

20
21
22
23
24
25
26
cd ${THIRDPARTY_HOME}
mkdir cmake
cd cmake
tar xf ${ARCHIVE_HOME}/cmake-3.7.2.tar.gz
mkdir cmake-3.7.2_prefix
cd cmake-3.7.2
export CMAKE_ROOT=$(realpath ../cmake-3.7.2_prefix)

Now configure the build environment, build, and install the generated system into $CMAKE_ROOT.

27
28
29
./configure --prefix=$CMAKE_ROOT |& tee ${CMAKE_CONFIGURE_LOG}
make |& tee ${CMAKE_MAKE_LOG}
make install |& tee ${CMAKE_INSTALL_LOG}

Prepend $CMAKE_ROOT to $PATH:

30
31
cd ${DEV_HOME}
export PATH=$CMAKE_ROOT/bin:$PATH
Optional step to create a script to restore $CMAKE_ROOT

This step is completely optional but can be used to create a script, cmake_path.sh that will restore the environment variable, $CMAKE_ROOT when invoked with source6.

export CMAKE_PATH_SH=${DEV_HOME}/cmake_path.sh
echo \#\!/bin/bash > ${CMAKE_PATH_SH}
echo export CMAKE_ROOT=${CMAKE_ROOT} >> ${CMAKE_PATH_SH}
echo chmod ug+x ${CMAKE_PATH_SH} >> ${CMAKE_PATH_SH}
chmod ug+xr ${CMAKE_PATH_SH}
If you do follow this step, you can restore the $CMAKE_ROOT environment variable by using the command:

source ${DEV_HOME}/cmake_path.sh
or
. ${DEV_HOME}/cmake_path.sh

(Used in this manner, '.' is an alias for ':::sh source`).

Building Boost 1.60.0

Boost is a collection of industry standard libraries that extend, and enhance, the C++ programming language, in which DCore is implemented. Because DCore was implemented using Version 1.60.0 we need to build a local version since the standard libraries distributed with Ubuntu 16.04 are too new.

First setup the logging:

32
33
export BOOST_BOOTSTRAP_LOG=${CURR_BUILD_LOGS}/boost-bootstrap.log
export BOOST_BUILD_LOG=${CURR_BUILD_LOGS}/boost-build.log

Now download the source code archive file:

34
35
cd $ARCHIVE_HOME
wget https://sourceforge.net/projects/boost/files/boost/1.60.0/boost_1_60_0.tar.gz 
In the $THIRDPARTY_HOME directory, create the required sub-directories, unpack the archive and create an environment variable ($BOOST_ROOT) that holds the location of the compiled library and include files:

36
37
38
39
40
41
mkdir ${THIRDPARTY_HOME}/boost
cd ${THIRDPARTY_HOME}/boost
tar xf ${ARCHIVE_HOME}/boost_1_60_0.tar.gz
mkdir boost-1.60.0_prefix
cd boost_1_60_0
export BOOST_ROOT=$(realpath ../boost-1.60.0_prefix)

Now configure the build environment, build, and install the generated system into ${BOOST_ROOT}.

42
43
44
./bootstrap.sh --prefix=$BOOST_ROOT |& tee ${BOOST_BOOTSTRAP_LOG}
./b2 install |& tee ${BOOST_BUILD_LOG}
cd ${DEV_HOME}
Optional step to create a script to restore $BOOST_ROOT

This step is completely optional but can be used to create a script, boost_path.sh that will restore the environment variable, $BOOST_ROOT when invoked with source6.

export BOOST_PATH_SH=${DEV_HOME}/boost_path.sh
echo \#\!/bin/bash > ${BOOST_PATH_SH}
echo export BOOST_ROOT=${BOOST_ROOT} >> ${BOOST_PATH_SH}
echo chmod ug+x ${BOOST_PATH_SH} >> ${BOOST_PATH_SH}
chmod ug+xr ${BOOST_PATH_SH}
If you do follow this step, you can restore the $CMAKE_ROOT environment variable by using the command:

source ${DEV_HOME}/boost_path.sh
or
. ${DEV_HOME}/boost_path.sh

(Used in this manner, '.' is an alias for ':::sh source`).

Downloading and Building DCore

The DCore source code needs to be retrieved from the Github repository:

45
46
47
48
49
 cd ${DEV_HOME}
 git clone https://github.com/DECENTfoundation/DECENT-Network
 cd DECENT-Network
 git submodule update --init --recursive
 git checkout

Next it is necessary to create the directory that will hold the build artifacts for DCore, and create environment variables that point to both the downloaded source directory ($DECENT_NETWORK) and the build directory ($DECENT_BUILD)

50
51
52
export DECENT_NETWORK=${DEV_HOME}/DECENT-Network
export DECENT_BUILD=${DECENT_NETWORK}-build
mkdir ${DECENT_BUILD}

The file ${DECENT_NETWORK}/libraries/wallet/wallet.cpp contains a line:

//#define DECENTGO
which needs to be uncommented:
#define DECENTGO

You can either do this manually, or use the following commands:

WALLET_CPP=${DECENT_NETWORK}/libraries/wallet/wallet.cpp
mv ${WALLET_CPP} ${WALLET_CPP}.COPY && sed -e "s/^\/\/\#define DECENTGO/\#define DECENTGO/" ${WALLET_CPP}.COPY > ${WALLET_CPP}

Next we will start to build DCore.

First move to the build directory, then invoke CMake to build the Makefiles. Status information relating to the progress of this command will be sent to both the terminal and the logfile named in $BUILD_CACHE_LOG.

53
54
cd ${DECENT_BUILD}
cmake -G "Unix Makefiles" -D CMAKE_BUILD_TYPE=Debug ${DECENT_NETWORK} |& tee ${BUILD_CACHE_LOG}

Next comes the actual build. Progress messages are sent to the terminal and are recorded in the logfile names in $BUILD_ALL_LOG.

55
cmake --build . --target all -- -j -l 3.0 |& tee ${BUILD_ALL_LOG}
'Simplifying' the build messages

The command line options "-j -l 3.0" allow the compiler to execute parallel builds on systems that are capable of supporting them. Unfortunately this means that compiler messages can be interleaved, making reading them tricky'. If this happens, re-run using the following command, instead:

cmake --build . --target all |& tee ${BUILD_ALL_LOG}

Some developers and admins prefer to compile in a single thread by default.

The final 'CMake' step builds executable versions:

56
cmake --build . --target install |& tee ${BUILD_INSTALL_LOG}

Set the binary path environment variable

export DECENT_BINS=${DECENT_BUILD}/artifacts/prefix/bin/
export PATH=$PATH:${DECENT_BINS}

Testing

We provide a public testnet as test environment, which is not connected with the production environment.

Follow this link to test the build and start using DCore.

Notes and Comments

locale::facet::_S_create_c_locale name not valid

When an attempt is made to execute decentd, an error similar to the following is thrown:

[email protected]:~$ ~/Projects/Decent/DECENT-Network-build/artifacts/prefix/bin/decentd
terminate called after throwing an instance of 'std::runtime_error'
what():  locale::facet::_S_create_c_locale name not valid
Aborted (core dumped)

The term locale8 refers to the 'localisation'8 of the server, which is the set of configuration settings, such as languages and time formats, that make it conform to the regional expectations.

This error means that something in that configuration is incomplete or corrupted and needs to be reconfigured.

Adding the following line of code to the .profile file of the account that DCore will be run from has been found to fix this error:

export LC_ALL=C; unset LANGUAGE
This thread on Github, for a project unrelated to DCore, provides more information, and a good example of finding help inplaces other than DCore documentation.

What is .profile and how do I edit it?

The optional $HOME/.profile file contains commands that modify the environment for an individual user account and will override the values set in the system wide default file, /etc/profile.

These files can be used to set search paths, prompts, locales, command macros (see alias)), among many other behavioural characteristics.

The first thing to mention is that since the file name, .profile begins with a ".", it is a hidden file. That means that, normally, the command ls ~ will not list the file in it's output unless the -a command line option is used. ie. ls -a ~.

If ls -a ~ does not reveal .profile then it does not exist and will need to be created if you wish to add commands to modify your environment.

We have found the following links to be useful. Please remember that these links are external to DECENT and any opinions expressed within them are not representative of this project. Please report any broken links, or offensive material to support so that we might update this resource.

Linux Tutorials

  1. https://ryanstutorials.net/linuxtutorial/
  2. http://www.ee.surrey.ac.uk/Teaching/Unix/

  1. It is possible that these build instructions will work on other Debian style distributions but no testing has been done. It is known that Ubuntu 17.10 does have some build issues which we are researching currently. 

  2. This image can be used directly by most virtual machine hypervisors (ie. VirtualBox), burned straight to a DVD with appropriate software4, or to create a bootable USB device

  3. These values were chosen conservatively after failures occurred while building with only 4 GB Ram available. It is possible that they can be more finely tuned to use smaller values. 

  4. Software to burn to DVD will be specific to the system you download the ISO file image on, and beyond the scope of this document. 

  5. sudo is a command that allows a user (who has permission to use the sudo command) the ability to operations normally only permitted to the root user. This is safer than being logged in as root since one has to specifically choose which commands to elevate to root permission level and helps reduce the risk of catastrophic mistakes and security breaches. See man sudo for more information. 

  6. source is a bash shell command that can be used to run a script that can change values in it's own environment. It is used here to 'import' environment variables. See the bash manpage for more information on bash, and its command, source. Information specific to source can be found in the Shell Builtin Commands section (It's a big page!). 

  7. Environment Variables act as a memory for your terminal and store information under easy to use names. In this case, they are used to store the names of files, their locations in the file systems and options that need to be set for the build process. Unless their definitions are placed in special files that the operating system will read, environment variables exist only while the terminal session in which they were instantiated exists. 

  8. Localisation is the process by which a computer program or system is modified to conform with regional or linguistic norms. That is, change the languages, direction or writing, number and date formats to those the user is familiar with. These are usually referred to as locales

    A good description of locales in Linux and more information from IBM. While not specifically for Ubuntu, the documentation is still relevant.