Random Number Generator (RNG)
Other Documentation
Docker Install
Setup SONs using a pre-configured Docker container
This document assumes that you are running Ubuntu 18.04. Other Debian based releases may also work with the provided script.
The following steps outline the Docker installation of a SON Node:
  1. 1.
    Preparing the Environment
  2. 2.
    Installing Docker
  3. 3.
    The Bitcoin node
  4. 4.
    Installing the peerplays:son image
  5. 5.
    Starting the environment
  6. 6.
    Using the CLI wallet
  7. 7.
    Update config.ini with SON Account Info

1. Preparing the Environment

1.1. Hardware requirements

Please see the general SON hardware requirements.
For the docker install, we'll be using a self-hosted Bitcoin node. The requirements that we'll need for this guide would be as follows:
Full Node?
SON Node?
Bitcoin node type
CPU
Memory
Storage
Bandwidth
OS
Yes
Yes
Self-Hosted, Reduced Storage
8 Cores
64GB
350GB SSD
1Gbps
Ubuntu 18.04

1.2. Installing the required dependencies

1
sudo apt-get update
2
sudo apt-get install vim git curl
Copied!
Then we'll clone the Peerplays Docker repository.
1
git clone https://gitlab.com/PBSA/tools-libs/peerplays-docker.git -b release
Copied!

2. Installing Docker

Note: It is required to have Docker installed on the system that will be performing the steps in this document.
Docker can be installed using the run.sh script inside the Peerplays Docker repository:
1
sudo ./run.sh install_docker
Copied!
Since the script has added the currently logged in user to the Docker group, you'll need to re-login (or close and reconnect SSH) for Docker to function correctly.
Note: You can look at https://docs.docker.com/engine/install/ to learn more on how to install Docker. Or if you are having permission issues trying to run Docker, use sudo or look at https://docs.docker.com/engine/install/linux-postinstall/

2.1. Setting up the .env file

Copy the example.env to .env located in the root of the repository:
1
cd ~/peerplays-docker
2
cp example.env .env
Copied!
We're going to have to make some changes to the .env file so we'll open that now using the Vim editor.
1
vim .env
Copied!
Here are the important parts of the .env file. These will be the parts that need to be edited or optionally edited. The rest of the file should be unchanged.
1
# Default SON wallet used inside bitcoind-node with ./run.sh start_son_regtest
2
# ***NOTE:*** You can change this if you like, but you'll also need to change the "bitcoin-wallet"
3
# setting in the Peerplays config.ini file to the same value!
4
SON_WALLET="son-wallet"
5
6
# Default bitcoin key used inside bitcoind-node with ./run.sh start_son_regtest
7
# Update this with your own Bitcoin Private Key!
8
BTC_REGTEST_KEY="XXXXXXXXXXXXX"
9
10
# Comma separated port numbers to expose to the internet (binds to 0.0.0.0)
11
# Expose 9777 to the internet, but only expose RPC ports 8090 and 8091 onto 127.0.0.1 (localhost)
12
# allowing the host machine access to the container's RPC ports via 127.0.0.1:8090 and 127.0.0.1:8091
13
# We'll need ports 8090 and 8091 open to our localhost to interact with the Peerplays CLI Wallet.
14
PORTS=9777,127.0.0.1:8090:8090,127.0.0.1:8091:8091
15
16
# Websocket RPC node to use by default for ./run.sh remote_wallet
17
REMOTE_WS=""
18
19
# This is the path to our Bitcoin node configuration file.
20
BTC_REGTEST_CONF="/home/ubuntu/.bitcoin/bitcoin.conf"
Copied!
IMPORTANT: You will need a Bitcoin Private Key of a wallet that you own on the Bitcoin mainnet. In the .env file above, you must replace BTC_REGTEST_KEY="XXXXXXXXXXXXX" with your own private key. So it may look something like BTC_REGTEST_KEY="cSKyTeXidmj93dgbMFqgzD7yvxzA7QAYr5j9qDnY9seyhyv7gH2m" for example.

3. The Bitcoin node

The Peerplays Docker package includes a Bitcoin node Docker container. The Bitcoin node will start up when we start the Peerplays Docker. We need to configure the Bitcoin node to run with reduced storage and network resources. As a Peerplays SON, we won't need to run a full Bitcoin node as we're only interested in the latest blocks.

3.1. Setting up the bitcoin.conf file

Since we'll be setting some custom config in our bitcoin.conf, we'll need to create and edit it now.
1
touch /home/ubuntu/.bitcoin/bitcoin.conf
2
vim /home/ubuntu/.bitcoin/bitcoin.conf
Copied!
The bitcoin.conf should look exactly like this (You can copy/paste the text in this code block into your editor):
1
# This config should be placed in following path:
2
# /home/ubuntu/.bitcoin/bitcoin.conf
3
4
# [core]
5
# Only download and relay blocks - ignore unconfirmed transaction
6
blocksonly=1
7
# Run in the background as a daemon and accept commands.
8
daemon=1
9
# Set database cache size in megabytes; machines sync faster with a larger cache. Recommend setting as high as possible based upon machine's available RAM.
10
dbcache=1024
11
# Reduce storage requirements by only storing most recent N MiB of block. This mode is incompatible with -txindex and -rescan. WARNING: Reverting this setting requires re-downloading the entire blockchain. (default: 0 = disable pruning blocks, 1 = allow manual pruning via RPC, greater than 550 = automatically prune blocks to stay under target size in MiB).
12
prune=10000
13
14
# [network]
15
# Bind to given address and always listen on it. (default: 0.0.0.0). Use [host]:port notation for IPv6. Append =onion to tag any incoming connections to that address and port as incoming Tor connections
16
bind=0.0.0.0
17
# Listen for incoming connections on non-default port.
18
port=8333
19
20
# [rpc]
21
# Accept command line and JSON-RPC commands.
22
server=1
23
# Accept public REST requests.
24
rest=1
25
# Bind to given address to listen for JSON-RPC connections. This option is ignored unless -rpcallowip is also passed. Port is optional and overrides -rpcport. Use [host]:port notation for IPv6. This option can be specified multiple times. (default: 127.0.0.1 and ::1 i.e., localhost, or if -rpcallowip has been specified, 0.0.0.0 and :: i.e., all addresses)
26
rpcbind=0.0.0.0
27
# Listen for JSON-RPC connections on this port
28
rpcport=8332
29
# Allow JSON-RPC connections from specified source. Valid for <ip> are a single IP (e.g. 1.2.3.4), a network/netmask (e.g. 1.2.3.4/255.255.255.0) or a network/CIDR (e.g. 1.2.3.4/24). This option can be specified multiple times.
30
rpcallowip=0.0.0.0/32
31
rpcuser=1
32
rpcpassword=1
33
34
# [zeromq]
35
# Enable publishing of block hashes to <address>.
36
zmqpubhashblock=tcp://0.0.0.0:11111
37
# Enable publishing of transaction hashes to <address>.
38
zmqpubhashtx=tcp://0.0.0.0:11111
39
# Enable publishing of raw block hex to <address>.
40
zmqpubrawblock=tcp://0.0.0.0:11111
41
# Enable publishing of raw transaction hex to <address>.
42
zmqpubrawtx=tcp://0.0.0.0:11111
43
44
45
# [Sections]
46
# Most options automatically apply to mainnet, testnet, and regtest networks.
47
# If you want to confine an option to just one network, you should add it in the relevant section.
48
# EXCEPTIONS: The options addnode, connect, port, bind, rpcport, rpcbind and wallet
49
# only apply to mainnet unless they appear in the appropriate section below.
50
51
# Options only for mainnet
52
[main]
53
54
# Options only for testnet
55
[test]
56
57
# Options only for regtest
58
[regtest]
Copied!
Save and quit the Vim editor.
Note: The settings in the config file above are set to reduce the requirements of the server. Block pruning and setting the node to Blocks Only save network and storage resources. For more information, see https://bitcoin.org/en/full-node#reduce-storage.

4. Installing the peerplays:son image

Use run.sh to pull the SON image:
1
cd ~/peerplays-docker
2
sudo ./run.sh install son
Copied!

4.1. Setting up config.ini file

There are many example configuration files, make sure to copy the right one. In this case it is: config.ini.son-exists.example
Copy the correct example configuration:
1
cd ~/peerplays-docker
2
cd data/witness_node_data_dir
3
cp config.ini.son-exists.example config.ini
Copied!
We'll need to make an edit to the config.ini file as well.
1
vim config.ini
Copied!
The important parts of the config.ini file (for now!) should look like the following. But don't forget to add your own Bitcoin public and private keys!
1
# Endpoint for P2P node to listen on
2
# p2p-endpoint =
3
4
# P2P nodes to connect to on startup (may specify multiple times)
5
# seed-node =
6
7
# JSON array of P2P nodes to connect to on startup
8
9
## Empty seed nodes means new network
10
# seed-nodes = []
11
12
## Connect to other SON nodes
13
# seed-nodes =
14
15
# Pairs of [BLOCK_NUM,BLOCK_ID] that should be enforced as checkpoints.
16
# checkpoint =
17
18
# Endpoint for websocket RPC to listen on
19
rpc-endpoint = 0.0.0.0:8090
20
21
# Endpoint for TLS websocket RPC to listen on
22
# rpc-tls-endpoint =
23
24
# The TLS certificate file for this server
25
# server-pem =
26
27
# Password for this certificate
28
# server-pem-password =
29
30
# File to read Genesis State from
31
genesis-json = /peerplays/son-genesis.json
32
33
# Block signing key to use for init witnesses, overrides genesis file
34
# dbg-init-key =
35
36
# JSON file specifying API permissions
37
# api-access =
38
39
# Space-separated list of plugins to activate
40
plugins = witness account_history market_history accounts_list affiliate_stats bookie peerplays_sidechain
41
42
# ==============================================================================
43
# peerplays_sidechain plugin options
44
# ==============================================================================
45
46
# ID of SON controlled by this node (e.g. "1.27.5", quotes are required)
47
# son-id = ""
48
49
# IDs of multiple SONs controlled by this node (e.g. ["1.27.5", "1.27.6"], quotes are required)
50
# son-ids = [""]
51
52
# Tuple of [PublicKey, WIF private key] (may specify multiple times)
53
# peerplays-private-key = ["", ""]
54
55
# IP address of Bitcoin node
56
bitcoin-node-ip = 172.0.0.1
57
58
# ZMQ port of Bitcoin node
59
bitcoin-node-zmq-port = 11111
60
61
# RPC port of Bitcoin node
62
bitcoin-node-rpc-port = 8332
63
64
# Bitcoin RPC user
65
bitcoin-node-rpc-user = 1
66
67
# Bitcoin RPC password
68
bitcoin-node-rpc-password = 1
69
70
# Bitcoin wallet
71
bitcoin-wallet = son-wallet
72
73
# Bitcoin wallet password
74
bitcoin-wallet-password = ""
75
76
# Tuple of [Bitcoin public key, Bitcoin private key] (may specify multiple times)
77
# This should be the public and private keys of the Bitcoin wallet you'll use. You already entered the private key in the .env file above.
78
bitcoin-private-key = ["", ""]
Copied!
Save the file and quit.

5. Starting the environment

Once the configuration is setup, use run.sh to start the peerplaysd and bitcoind containers:
1
cd ~/peerplays-docker
2
3
# You'll also want to set the shared memory size (use sudo if not logged in as root).
4
# Adjust 64G to whatever size is needed for your type of server and make sure to leave growth room.
5
# Please be aware that the shared memory size changes constantly. Ask in a witness chatroom if you're unsure.
6
./run.sh shm_size 64G
7
8
# It's recommended to set vm.swappiness to 1, which tells the system to avoid using swap
9
# unless absolutely necessary. To persist on reboot, place in /etc/sysctl.conf
10
sysctl -w vm.swappiness=1
11
12
# Start the SON environment
13
./run.sh start_son_regtest
Copied!
The SON network will be created and the seed (peerplaysd) and bitcoind-node (bitcoind) containers will be launched. To check the status, inspect the logs:
1
./run.sh logs
Copied!
This will give an output similar to:
(logs showing healthy connection to GLADIATOR)
If the logs are not looking healthy, perform a replay.
1
# replay the blockchain
2
./run.sh replay_son
Copied!

6. Using the CLI wallet

After starting the environment, the CLI wallet for the seed (peerplaysd) will be available.

6.1. Connecting to the blockchain with the CLI Wallet

Open another terminal and use docker exec to connect to the wallet.
1
# In the local terminal
2
docker exec -it seed cli_wallet
Copied!
NOTE: If an exception is thrown and contains Remote server gave us an unexpected chain_id, then copy the remote_chain_id that is provided by it. Pass the chain ID to the CLI wallet:
1
# In the local terminal
2
docker exec -it seed cli_wallet --chain-id=<CHAIN-ID>
Copied!
Set a password for the wallet and then unlock it:
1
# In the CLI wallet
2
set_password <YOUR-WALLET-PASSWORD>
3
unlock <YOUR-WALLET-PASSWORD>
Copied!
The CLI wallet will show unlocked >>> when successfully unlocked
Note: A list of CLI wallet commands is available here: https://devs.peerplays.tech/api-reference/wallet-api/wallet-calls
Assuming we're starting without any account, it's easiest to create an account with the Peerplays GUI Wallet. The latest release is located here https://github.com/peerplays-network/peerplays-core-gui/releases/latest. When you create an account with the GUI wallet, you should have a username and password. We'll need those for the next steps. First we'll get the private key for the new account.
1
# In the cli_wallet...
2
3
get_private_key_from_password <put your username here> active <put your password here>
4
5
# For example:
6
# get_private_key_from_password mynew-son active LExu4QtSapqzdEaly2RwMugul3GhedTf234IiF2zzzfU4nuKXow8
7
8
# The program will return a tuple of the public and private keys for your account.
9
# That will look something like this:
10
# [
11
# "PPY...random.numbers.and.letters...",
12
# "5...random.numbers.and.letters..."
13
# ]
Copied!
The key beginning with "PPY" is the public key. The key beginning with "5" is the private key. We'll need to import this private key into the cli_wallet.
1
# In the cli_wallet...
2
3
import_key "mynew-son" 5...random.numbers.and.letters...
4
5
# If this is successful, the return is simply
6
# true
Copied!
Next we'll upgrade the account to a lifetime membership.
Note: At the time of writing this guide, this costs 5 PPY to perform this operation. You'll need that in your account first!
1
# In the cli_wallet...
2
3
upgrade_account mynew-son true
Copied!
Next we'll create the vesting balances.
1
# In the cli_wallet...
2
3
create_vesting_balance mynew-son 50 PPY son true
4
create_vesting_balance mynew-son 50 PPY normal true
5
get_vesting_balances mynew-son
6
7
# The return here will show us the IDs of the vesting balances.
8
# For example:
9
# [{
10
# "id": "1.13.79",
11
# "owner": "1.2.58",
12
# ...
13
# },{
14
# "id": "1.13.80",
15
# "owner": "1.2.58",
16
# ...
17
# }
18
# ]
Copied!
Now we have all the info we need to create a SON account.
1
# In the cli_wallet...
2
3
create_son mynew-son "https://www.mynew-son.com" 1.13.79 1.13.80 [[bitcoin, 023b907586045625367ecd62c5d889591586c87e57fa49be21614209489f00f1b9]] true
4
5
# The above command is structured like this:
6
# create_son <username> "<SON proposal url>" <son vesting balance ID> <normal vesting balance ID> [[bitcoin, <bitcoin public key>]] true
Copied!
To get the SON ID:
1
# In the cli_wallet...
2
3
get_son mynew-son
4
5
# Which returns:
6
# {
7
# "id": "1.27.16",
8
# ...
9
# }
Copied!
We'll set the signing key using the active key from the owning account:
1
# In the cli_wallet...
2
3
# First we'll get the active key of the owning account.
4
get_account mynew-son
5
6
# In the return, we're looking for the
7
# "active":
8
# ...
9
# { ... "key_auths":
10
# [[ "PPY7SUmjftH3jL5L1YCTdMo1hk5qpZrhbo4MW6N2wWyQpjXkT7ByB",
11
# ...
12
13
# Using the active public key we just found:
14
get_private_key PPY7SUmjftH3jL5L1YCTdMo1hk5qpZrhbo4MW6N2wWyQpjXkT7ByB
15
16
# This will return the private key.
17
# "5JKvPJkerMNVEubsbKN8Xd8wGaU1ifhv7xAwy9gFJP6yMEoTkSd"
18
19
# Then we update the signing key using the public key.
20
update_son mynew-son "" "PPY7SUmjftH3jL5L1YCTdMo1hk5qpZrhbo4MW6N2wWyQpjXkT7ByB" [[bitcoin, 023b907586045625367ecd62c5d889591586c87e57fa49be21614209489f00f1b9]] true
Copied!
Now we have our SON account ID and the public and private keys for the SON account. We'll need this for the config.ini file.

7. Update config.ini with SON Account Info

Lets stop the node for now so we can finish up the config.ini.
1
cd ~/peerplays-docker
2
./run.sh stop
Copied!
Ensure the following config settings are in the config.ini file under the peerplays_sidechain plugin options.
1
cd data/witness_node_data_dir
2
vim config.ini
Copied!
1
# In the config.ini file...
2
3
# ID of SON controlled by this node (e.g. "1.27.5", quotes are required)
4
son-id = "1.27.16"
5
6
# Tuple of [PublicKey, WIF private key] (may specify multiple times)
7
peerplays-private-key = ["PPY7SUmjftH3jL5L1YCTdMo1hk5qpZrhbo4MW6N2wWyQpjXkT7ByB", "5JKvPJkerMNVEubsbKN8Xd8wGaU1ifhv7xAwy9gFJP6yMEoTkSd"]
Copied!
Then it's just a matter of starting the node back up!
1
# replay the blockchain
2
./run.sh replay_son
Copied!

8. Related Documents

Vim is a text editing program available for Ubuntu 18.04. See vim.org