Blockscout deployment guide

This guide currently uses the following software versions:

Ubuntu-18.04 (Bionic) server
Openethereum (Parity): v3.0.1-stable
BlockScout: v3.2.0

General Pre-Requirements

Linux(Ubuntu or CentOS) server with root access, 4+ TB storage for BlockScout database, 2+ TB storage for ETH Mainnet archive node

Create a user with sudo privileges, ssh access, domain name, ensure basic server security

Openethereum setup

Openethereum Pre-Install

Prepare storage

Make sure your user has access to the storage mount/path AE: /mnt/openeth/storage/path

Get binary

Install basic deps: build-essential cmake libudev-dev

Download the latest precompiled version from here

\$ sudo apt-get update && sudo apt-get upgrade -y
\$ sudo apt-get install libudev-dev zip unzip build-essential cmake -y
\$ wget https://github.com/openethereum/openethereum/releases/download/version/openethereum-linux-version.zip
\$ unzip -o openethereum-linux-version.zip -d openethereum
\$ cd openethereum
\$ chmod +x ./openethereum

Configuration

Create an empty log file

\$ touch /mnt/openeth/storage/path/config/example.log

Write configuration file, AE:

\$ nano /mnt/openeth/storage/path/config.toml
[parity]
mode = "active"
release_track = "stable"
base_path = "/opt/.local/share/io.parity.ethereum"

[network]
warp = false

[misc]
log_file = "/mnt/openeth/storage/path/config/example.log"

Prepare the systemd service file

\$ sudo nano /etc/systemd/system/openethereum.service
[Unit]
Description=OpenEthereum
After=network.target

[Service]
User=youruser
Group=yourusergroup
ExecStart=/usr/bin/openethereum -c /mnt/openeth/storage/path/config.toml --jsonrpc-interface all --jsonrpc-apis  web3,eth,net,parity,pubsub,traces --ws-interface all --fat-db=on --pruning=archive --ws-apis all --ws-origins all --ws-hosts  all
Restart=on-failure
KillSignal=SIGHUP

[Install]
WantedBy=default.target

Allow the ports used by the openethereum client (ports 30303/tcp, 8545/tcp, 8546/tcp) through your firewall.

Test the systemd service

\$ sudo systemctl daemon-reload
\$ sudo systemctl start openetherum

Enable openethereum as service

\$ sudo systemctl enable openethereum.service

PostgreSQL setup

PostgreSQL Pre-Install

Prepare and mount storage for BlockScout DB

Install PostgreSQL

PostgreSQL downloads page suggests usage of different repositories based on the OS. For example, in Ubuntu:

\$ sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
\$ wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
\$ sudo apt-get update
\$ sudo apt-get install postgresql-10

PostgreSQL configuration

Create a new user in the OS and set a password using adduser

\# adduser dbusername

Create a database, user and set userpassword

\# su - postgres
\$ createuser --interactive dbusername
\$ createdb blockscout
\$ psql
\=\# ALTER USER dbusername WITH PASSWORD 'dbuserpassword';
\=\# GRANT ALL PRIVILEGES ON blockscout TO dbusername;
\=\# \q

Set your storage path as psql datadir

\$ nano /etc/postgresql/10/main/postgresql.conf

...
data_directory = '/mnt/psql/storage/path'          # use data in another directory
...

Make sure the PSQL user has the right permissions on storage dir.

Start psql

\$ sudo systemctl start postgresql

Validate data directory path

\# su - postgres
\$ psql
\=\# SHOW data_directory;

    data_directory
---------------------
 /mnt/psql/storage/path
(1 row)

\=\# \q

Make sure your user has blockscout db access

\# su - dbusername
\$ psql -d blockscout

Optionally, you might open the PostgreSQL port on your firewall: 5432/tcp to access it from a remote computer, but we don’t recommend it.

Enable postgresql as service

\$ sudo systemctl enable postgresql

BlockScout dependencies setup

Get base dependencies from apt: (yum/dnf on CentOS)

\$ sudo apt-get update
\$ sudo apt-get install git \
                       automake \
                       libtool inotify-tools \
                       libgmp-dev \
                       libgmp10 \
                       build-essential \
                       cmake -y

Erlang

Get official release here

Example on Ubuntu:

\$ wget https://packages.erlang-solutions.com/erlang/debian/pool/esl-erlang_version~ubuntu~bionic_amd64.deb
\$ sudo apt install ./esl-erlang_version~ubuntu~bionic_amd64.deb

Check version and installation:

\$ erl --version

Elixir

Download pre-compiled release from github

\$ wget https://github.com/elixir-lang/elixir/releases/download/tag/Precompiled.zip
\$ unzip -o Precompiled.zip -d elixir

Add elixir bin to path (for permanent effect, append it to your user bash profile)

\$ export PATH="$PATH:/path/to/elixir/bin"
\$ nano ~/.profile
...
export PATH="$PATH:/path/to/elixir/bin"

Check version and installation:

\$ elixir --version

Node.js

You can get Node.js here or in your distro repos:

\$ curl -sL https://deb.nodesource.com/setup_version | sudo -E bash -
\$ sudo apt-get update
\$ sudo apt-get install -y nodejs

Check Node version:

\$ nodejs --version

BlockScout installation

Get latest master from git:

\$ git clone https://github.com/poanetwork/blockscout
\$ cd blockscout

Generate DB secret and export it to bash:

\$ mix phx.gen.secret    # in blockscout base dir
\$ export SECRET_KEY_BASE=<generatedAboveSecret/PasteHere>

Set required env variables, example below is suited for Ethereum Mainnet and Parity(Openethereum)

\$ export ETHEREUM_JSONRPC_HTTP_URL=http://localhost:8545
\$ export COIN=ETH
\$ export SUBNETWORK=Mainnet
\$ export NETWORK=Ethereum
\$ export DATABASE_URL=postgresql://dbusername:dbpassword@localhost:5432/blockscout

Install mix deps, create db, run migrations:

\$ mix do deps.get, local.rebar --force, deps.compile, compile  # in blockscout base dir
\$ mix do ecto.create, ecto.migrate

Install Node.js deps, build static assets:

\$ cd apps/block_scout_web/assets; npm install && node_modules/webpack/bin/webpack.js --mode production; cd -
\$ cd apps/explorer && npm install; cd -
\$ mix phx.digest

Enable SSL:

\$ cd apps/block_scout_web; mix phx.gen.cert blockscout blockscout.local; cd -

The above command will generate and enable self-signed ssl certs, you need to replace them with real ones. You may use certbot (letsencrypt) to do it, don’t forget to set user permissions and configure the file: /path/to/blockscout/config/dev.exs, see example below:

\$  nano /path/to/blockscout/config/dev.exs
...
config :block_scout_web, BlockScoutWeb.Endpoint,
  http: [port: 4000],
  https: [
    port: 4001,
    cipher_suite: :strong,
    certfile: "priv/cert/cert.pem",
    keyfile: "priv/cert/privkey.pem"
  ]
...

If using certbot, add cert renewal to crontab

Set BlockScout as systemd service

Prepare BlockScout start script. You need to export all required env vars before each run:

\$ nano /path/to/blockscout/start.sh

#!/bin/bash
export PATH="$PATH:/home/scout/elixir/bin"
export ETHEREUM_JSONRPC_HTTP_URL=http://localhost:8545
export COIN=ETH
export SUBNETWORK=Mainnet
export NETWORK=Ethereum
export DATABASE_URL=postgresql://dbusername:dbpassword@localhost:5432/blockscout
/path/to/elixir/bin/mix phx.server

\$ chmod +x /path/to/blockscout/start.sh

Set your start script as service:

\$ sudo nano /etc/systemd/system/blockscout.service

 [Unit]
 Description=Blockscout
 After=network.target

 [Service]
 User=youruser
 Group=yourusergroup
 WorkingDirectory=/full/path/to/blockscout
 ExecStart=/bin/bash /path/to/blockscout/start.sh
 KillSignal=SIGHUP

 [Install]
 WantedBy=default.target

Open explorer ports on firewall default 4000/tcp 4001/tcp

Test run:

\$ sudo systemctl start blockscout

Enable blockscout as a service:

\$ sudo systemctl enable blockscout.service

Blockscout deployment guide#

General Pre-Requirements#

Openethereum setup#

Openethereum Pre-Install#

Get binary#

Configuration#

PostgreSQL setup#

PostgreSQL Pre-Install#

Install PostgreSQL#

PostgreSQL configuration#

BlockScout dependencies setup#

Erlang#

Elixir#

Node.js#

BlockScout installation#

Set BlockScout as systemd service#