HF18: Данные по установке

Документ содержит инструкцию по начальной установке и запуску, а также обновлению программного продукта GolosChain на сервере под управлением операционной системы Ubuntu 16.04 либо иной системы семейства Linux с помощью программного обеспечения Docker.

Способы установки HF•18

Установку HF•18 на сервер можно выполнить в одном из следующих вариантов: 1. установка с использованием доступной платформы Docker; 2. изначальное построение непосредственно из исходников golosd под управлением операционной системы Ubuntu; 3. обновление GolosChain до версии HF•18 из исходников golosd под управлением операционной системы Ubuntu.

Инструкции по установке HF•18 в вариантах 1-3 изложены в разделах 2, 3 и 4 соответственно.

Рекомендуется установку HF•18 выполнять в варианте 1, поскольку использование платформы Docker обеспечивает:

• создание необходимого программного окружения, в том числе необходимого перечня библиотек, независимо от версии операционной системы;

• создание среды, изолированной от ненужных временных файлов, сохраняемых системой в строящемся пространстве.

Рекомендации к характеристикам аппаратных и программных средств

Сервер, на который устанавливается HF•18, должен иметь характеристики не хуже:

• объем оперативной памяти:

  • 16 ГБ для делегатского Узла в варианте конфигурации LOWMEM;

  • 64 ГБ для API Узла в полной конфигурации;

• объем дисковой памяти: 80 ГБ для API Узла в полной конфигурации;

• операционная система:

  • Ubuntu версии 16.04 (или более поздней);

  • Linux-система (для установки HF•18 с использованием платформы Docker).

Программный код golosd поддерживает следующие программные обеспечения:

• базовая библиотека: boost версии 1.58;

• компилятор GCC версии 5.х (с поддержкой стандарта С++14).

Иные рекомендации

Перед началом выполнения приведенных в руководстве действий настоятельно рекомендуется:

• сохранить код личного ключа;

• отключить функцию подписания блоков отключением плагина witness;

• остановить и удалить предыдущую версию GolosChain (только для обновления версии), используя следующие команды:

  docker stop golos-default
  docker rm golos-default

Раздел_2 Установка HF•18 с использованием платформы Docker

Для построения HF•18 требуется сервер с операционной системой Ubuntu 16.04 и определенным набором библиотек. В случае отсутствия сервера с требуемой операционной системой следует воспользоваться сервером с операционной системой семейства Linux. Имеется возможность установки HF•18 на такой сервер с помощью платформы Docker, обеспечивающий создание необходимого окружения, независимо от версии системы Linux.

Установка и функционирование HF•18 на сервер под управлением каких-либо иных классов систем не поддерживается.

Для установки HF•18 на сервер с использованием платформы Docker необходимо выполнить следующие операции: 1. сконфигурировать Docker-образ в отдельном пространстве; 2. создать контейнер с использованием Docker-образа. Контейнер можно размещать как на локальном компьютере, так и на удаленном или виртуальном; 3. воспроизвести блокчейн.

Конфигурирование Docker-образа

1. Создать репозиторий golosd в отдельном пространстве и установить значения переменных в конфигурационных файлах.

2. В командном окне войти в директорию, в которой будет создан Docker-образ, и исполнить:

git clone https://github.com/golos-blockchain/golos.git

В пространство, из которого была исполнена команда, должен скопироваться каталог golos с его содержимым. В процессе копирования не должны появляться сообщения об ошибках.

3. Создать отдельную директорию для конфигурационных файлов, исполнив:

sudo mkdir -p /etc/golosd

4. В созданную директорию /etc/golosd скопировать конфигурационные файлы. Используемые для копирования команды:

cd golos
sudo cp share/golosd/seednodes /etc/golosd/
sudo cp share/golosd/config/config.ini /etc/golosd/

В директории golosd находятся несколько конфигурационных файлов, данные которых можно использовать в качестве базовых для создания необходимого окружения. В следующей таблице приведен перечень основных конфигурационных файлов и их назначение.

Конфигурационный файл	Назначение
share/golosd/config/config.ini	Содержит набор переменных для создания API Узла в полной его конфигурации со всеми включенными плагинами
share/golosd/config/config_witness.ini	Содержит набор переменных для создания делегатского Узла в конфигурации по умолчанию. Используется делегатами для подписания блоков
share/golosd/config/config_stock_exchange.ini	Содержит набор переменных для создания Узла для биржевых операций в конфигурации по умолчанию

Поскольку golosd обрабатывает конфигурационный файл только с именем config.ini, то в зависимости от решаемой задачи следует выбрать необходимый конфигурационный файл и скопировать значения его переменных окружения в share/golosd/config/config.ini.

В следующей таблице приведен рекомендуемый перечень переменных окружения, значения которых необходимо установить.

Переменная окружения	Назначение
witness	Устанавливает имя аккаунта делегата (для делегатского Узла)
private-key	Задает код личного ключа active (для делегатского Узла). Тип ключа может быть отличным от active
plugin	Определяет перечень плагинов. Неиспользуемые плагины могут быть удалены

Количество задаваемых плагинов в переменной plugin влияет на объем используемой памяти, а также быстродействие Узла. Минимальный набор плагинов приведен в файле config_witness.ini.

5. Создать директорию для размещения в ней блокчейна, исполнив:

sudo mkdir -p /var/lib/golosd/

6. В созданную директорию скопировать исходный genesis-файл, исполнив:

sudo cp share/golosd/snapshot5392323.json /var/lib/golosd/

Запуск Docker-образа из GolosCore

Docker-образ размещается на общедоступном реестре Docker Hub либо создается локально из исходников GolosCore. Из Docker-образа можно создать контейнер на физическом устройстве, на котором установлен Docker. Docker-образ представляет собой тиражируемый образ некоторого объекта, а создаваемый контейнер является самим объектом, который можно запускать и останавливать. Контейнер является изолированным от внешней среды со своими переменными окружения и параметрами запуска. В среде контейнера исполняется Узел. Для запуска одного и того же Узла требуется создание другого контейнера.

Для запуска Docker-образа из GolosCore и создания контейнера исполнить следующую командную строку:

sudo docker run -d \
    -p 4243:4243 \
    -p 8090:8090 \
    -p 8091:8091 \
    -v /etc/golosd:/etc/golosd \
    -v /var/lib/golosd:/var/lib/golosd \
    --name golos-default  golosblockchain/golos:latest

где: -d — устанавливает запуск контейнера в фоновом режиме; -p — устанавливает привязку конкретных портов хоста к портам контейнера; --name — задает имя контейнера (golos-default); latest — задает последнюю официальную версию golosd.

Для проверки успешного запуска контейнера исполнить команду

sudo docker ps

Создание контейнера считается успешным, если в тексте лог-файла не было сообщений об ошибках и в выдаче этой команды появится имя контейнера golos-default с соответствующими портами.

Воспроизведение блокчейна

Перед тем, как приступить к непосредственному воспроизведению блокчейна, убедиться в наличии файлов /var/lib/golosd/blockchain/block_log и /var/lib/blockchain/block_log.index.

В файле block_log хранится список подписанных блоков с транзакциями. В каждой из транзакций содержится перечень операций, которые необходимо выполнить для восстановления состояния системы. Все блоки взаимосвязаны между собой. В процессе появления новых блоков они считываются по сети, добавляются в этот файл и могут быть использованы в дальнейшем. Файл представляет собой протокол всех операций, как ранее совершенных системой,так и последующих.

В файле shared_memory.bin хранятся данные о состоянии системы, а также непосредственно база данных, в том числе таблицы с записями и индексы, по которым происходит обращение к ячейкам таблицы.

В каждом из плагинов, подобно структуре файла shared_memory.bin, содержатся таблицы и индексы, требующие из наполнения с самого начала истории. Во время включения дополнительного плагина его поля остаются пустыми и для их заполнения требуется воспроизведение всех операций из block_log с самого начала. Этот процесс состоит из множества операций, требующий обработку каждого блока.

Поскольку операция считывания отдельного блока по сети значительно превышает по времени операцию считывания из локальной области, использование block_log значительно сокращает время процессов блокчейна.

Для воспроизведения блокчейна необходимо следовать следующим указаниям.

1. Убедиться, что процессы контейнера golos-default завершены, используя следующую командную строку:

sudo docker ps | grep golos-default

Если имеется незавершенный процесс, его необходимо остановить, исполнив:

sudo docker stop golos-default

2. Запустить контейнер, используя в качестве основы образ, исполнив:

sudo docker run -d \
    -p 4243:4243 \
    -p 8090:8090 \
    -p 8091:8091 \
     -v /etc/golosd:/etc/golosd \
    -v /var/lib/golosd:/var/lib/golosd \
    --name golos-default  golosblockchain/golos:latest

где: golos-default — имя контейнера; latest — задает последнюю официальную версию golosd.

3. Воспроизвести блокчейн посредством запуска скрипта golosdctl внутри запущенного контейнера golos-default:

sudo docker exec golos-default /usr/local/bin/golosdctl replay

4. Выполнить проверку успешной установки Узла.

• Открыть лог-файл и убедиться в следующих фактах:

  • в файл прекращено поступление новой информации;

  • текст файла не содержит сообщения об ошибках.

• Подключиться к Узлу через cli_wallet по порту 8091, исполнив:

  sudo docker exec -ti golos-default \
    /usr/local/bin/cli_wallet \
    --wallet="/var/lib/golosd/wallet.json" \
    --server-rpc-endpoint="ws://127.0.0.1:8091"

  Успешное подключение будет означать успешную установку Узла.

Построение Docker-образа с использованием Docker-файла

В этом разделе приведена инструкция по построению Docker-образа с использованием различных Docker-файлов.

Docker-файл представляет собой текстовый файл с инструкциями, необходимыми для создания образа контейнера. Образ строится автоматически последовательным выполнением команд, приведенных в файле.

Docker-образ образует многоуровневую последовательность операций, каждый уровень которой представляет собой инструкции Docker-файла. Каждая инструкция создает отдельный уровень Docker-образа. При запуске Docker-образа и создании контейнера добавляется очередной уровень для записи изменений поверх нижнего уровня.

В зависимости от решаемой задачи можно построить Узел с соответствующими для этой задачи параметрами. В этом случае Docker-образ может быть построен с использованием одного из Docker-файлов, размещенных в каталоге share/golosd/docker/. Пользователю также предоставляется возможность самостоятельно создавать Docker-файл с необходимыми для его нужд параметрами для построения соответствующего контейнера.

В следующей таблице приведен перечень основных Docker-файлов и их назначение.

Docker-файл	Назначение
Dockerfile	Содержит набор инструкций и переменных для создания Docker-образа по умолчанию
share/golosd/docker/Dockerfile-small	Docker-файл с инструкциями одного уровня. Позволяет создать Docker-образ меньшего размера относительно Docker-образа, построенного по умолчанию
share/golosd/docker/Dockerfile-lowmem	Содержит набор переменных, направленных на экономию ресурсов, в том числе потребление памяти. Позволяют сконфигурировать Узел, не сохраняющий посты и комментарии
share/golosd/docker/Dockerfile-lowmem-small	Docker-файл с инструкциями одного уровня. Содержит набор переменных, позволяющих снизить потребление памяти

Для построения Docker-образа необходимо следовать следующим указаниям.

1. Удалить ранее установленный образ, исполнив:

sudo docker image rm local/golos

2. Выбрать из размещенного в каталоге share/golosd/docker/ набора нужный Docker-файл и построить Docker-образ, используя следующую команду:

sudo docker build -t local/golos -f Dockerfile

3. Запустить контейнер, исполнив:

sudo docker run -d \
    -p 4243:4243 \
    -p 8090:8090 \
    -p 8091:8091 \
    -v /etc/golosd:/etc/golosd \
    -v /var/lib/golosd:/var/lib/golosd \
    --name golos-default  local/golos

где: golos-default — имя запущенного контейнера; local/golos — показывает, что построение Docker-образа выполняется с использованием сети.

Перечень команд, применяемых к любому виду контейнера

1. Доступ к контейнеру:

sudo docker exec -ti golos-default /bin/bash

2. Получение текста лог-файла о контейнере:

sudo docker logs --tail 10 -f golos-default

3. Воспроизведение контейнера:

sudo docker exec golos-default /usr/local/bin/golosdctl replay

4. Подключение через cli_wallet к Узлу для проверки его функционирования:

sudo docker exec -ti golos-default \
    /usr/local/bin/cli_wallet \
    --wallet="/var/lib/golosd/wallet.json" \
    --server-rpc-endpoint="ws://127.0.0.1:8091"

5. Запуск контейнера:

sudo docker start golos-default

6. Останов контейнера:

sudo docker stop golos-default

Раздел_3 Обновление до новой версии

В этом разделе приведена инструкция по обновлению ранее установленного GolosChain до его новой версии HF•18.

Для обновления GolosChain необходимо следовать следующим указаниям.

1. Обновить исходные файлы, исполнив:

git clone https://github.com/golos-blockchain/golos.git
cd golos
git submodule update --init --recursive -f

2. Задать значения макро-переменных и сконфигурировать проект, исполнив:

mkdir build
cd build
cmake \
    -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_GOLOS_TESTNET=FALSE \
    -DBUILD_SHARED_LIBRARIES=FALSE \
    -DLOW_MEMORY_NODE=FALSE \
    -DCHAINBASE_CHECK_LOCKING=FALSE \
    ..

3. Построить проект с установкой демона в /usr/local/, исполнив:

make -j $(nproc)
sudo make install

4. Открыть конфигурационный файл share/golosd/config/config.ini и установить в нем значения переменных окружения. В зависимости от решаемых задач можно установить значения переменных окружения, обеспечивающих создание Узлов следующих типов:

• API Узел в полной конфигурации со всеми включенными плагинами;

• Узел делегатский, содержащий минимальный набор включенных плагинов;

• Узел в произвольной конфигурации с произвольным набором включенных плагинов.

В следующей таблице приведен рекомендуемый перечень переменных окружения, значения которых необходимо установить.

Переменная окружения	Назначение
witness	Устанавливает имя аккаунта делегата (для делегатского Узла)
private-key	Задает код личного ключа active (для делегатского Узла). Тип ключа может быть отличным от active
plugin	Определяет перечень плагинов. Неиспользуемые плагины могут быть удалены

Количество задаваемых плагинов в переменной plugin влияет на объем используемой памяти, а также быстродействие Узла. Минимальный набор плагинов приведен в файле config_witness.ini.

5. Остановить незавершенные процессы старой версии на демоне. В зависимости от конфигурации останов может быть выполнен различными способами, например, с помощью следующих команд:

pkill -15 golosd
sudo sv stop golosd

6. Воспроизвести блокчейн. Предварительно убедиться в наличии файлов /var/lib/golosd/blockchain/block_log и /var/lib/blockchain/block_log.index, в которых хранятся блоки и данные о состоянии системы и плагинов. Использование данных этих файлов избавляет от выполнения длительной операции синхронизации блоков по сети и, следовательно, сокращает время воспроизведения блокчейна.

Исполнить:

/usr/local/bin/golosd --replay-blockchain

7. Выполнить проверку успешного обновления GolosChain

• Открыть лог-файл и убедиться в следующих фактах:

  • в файл прекращено поступление новой информации;

  • текст файла не содержит сообщения об ошибках.

• Подключиться к Узлу через cli_wallet по порту 8091, исполнив:

  /usr/local/bin/cli_wallet \
    --wallet="/var/lib/golosd/wallet.json" \
    --server-rpc-endpoint="ws://127.0.0.1:8091"

  Успешное подключение к Узлу будет означать успешное обновление.

Раздел_4 Изначальная установка блокчейна

Для установки обновленной версии GolosChain необходимо следовать следующим указаниям.

1. Создать на сервере пространство для размещения в нем репозитория golosd.

2. Установить необходимые пакеты. Система Ubuntu 16.04 обеспечивает автоматический поиск в сети требуемого набора пакетов и загрузку их в соответствующие им директории. Для этого необходимо исполнить:

sudo apt-get update

sudo apt-get install -y \
        autoconf \
        automake \
        autotools-dev \
        bsdmainutils \
        build-essential \
        cmake \
        doxygen \
        git \
        ccache \
        libboost-all-dev \
        libreadline-dev \
        libssl-dev \
        libtool \
        ncurses-dev \
        pbzip2 \
        pkg-config \
        python3 \
        python3-dev \
        python3-pip \
        runit

sudo pip3 install gcovr

3. В отведенное для репозитория место скопировать исходные файлы из github, используя следующие команды:

git clone https://github.com/golos-blockchain/golos.git && cd golos

git submodule update --init --recursive -f

В процессе копирования не должны появляться сообщения об ошибках.

4. Задать значения макро-переменных и сконфигурировать проект, используя следующие команды:

mkdir build && cd build

cmake \
    -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_GOLOS_TESTNET=FALSE \
    -DBUILD_SHARED_LIBRARIES=FALSE \
    -DLOW_MEMORY_NODE=FALSE \
    -DCHAINBASE_CHECK_LOCKING=FALSE \
    ..

5. Построить проект с установкой демона в /usr/local/, исполнив:

make -j $(nproc) && sudo make install

Если была нужна сборка cli_wallet, последующие шаги не требуются, достаточно запустить приложение.

6. Создать пользователя с именем golosd для демона:

sudo useradd -s /bin/bash -m -d /var/lib/golosd golosd

7. Скопировать исходный файл genesis формата JSON для блокчейна, исполнив:

sudo cp ../share/golosd/snapshot5392323.json /var/lib/golosd/

8. Создать директорию golosd в /etc/ и скопировать в нее конфигурационные файлы:

sudo mkdir -p /etc/golosd
sudo cp ../share/golosd/seednodes /etc/golosd/
sudo cp ../share/golosd/config/config.ini /etc/golosd/

9. Сменить имя владельца скопированным конфигурационным файлам:

sudo chown golosd:golosd -R /etc/golosd/

10. Создать сервисный файл для демона:

sudo mkdir -p /etc/service/golosd
sudo cp ../share/golosd/golosd.sh /etc/service/golosd/run
sudo chmod +x /etc/service/golosd/run

11. Запустить функционирование GolosChain, исполнив:

sudo sv start golosd

12. Выполнить проверку успешной установки.

• Открыть лог-файл и убедиться в следующих фактах:

  • в файл прекращено поступление новой информации;

  • текст файла не содержит сообщения об ошибках.

• Подключиться к Узлу через cli_wallet по порту 8091, исполнив:

  /usr/local/bin/cli_wallet \
    --wallet="/var/lib/golosd/wallet.json" \
    --server-rpc-endpoint="ws://127.0.0.1:8091"

Успешное подключение к Узлу будет означать успешную установку GolosChain.