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.
Last modified 2yr ago
Конфигурационный файл	Назначение
share/golosd/config/config.ini	Содержит набор переменных для создания API Узла в полной его конфигурации со всеми включенными плагинами
share/golosd/config/config_witness.ini	Содержит набор переменных для создания делегатского Узла в конфигурации по умолчанию. Используется делегатами для подписания блоков
share/golosd/config/config_stock_exchange.ini	Содержит набор переменных для создания Узла для биржевых операций в конфигурации по умолчанию
Переменная окружения	Назначение
witness	Устанавливает имя аккаунта делегата (для делегатского Узла)
private-key	Задает код личного ключа `active` (для делегатского Узла). Тип ключа может быть отличным от `active`
plugin	Определяет перечень плагинов. Неиспользуемые плагины могут быть удалены
Docker-файл	Назначение
Dockerfile	Содержит набор инструкций и переменных для создания Docker-образа по умолчанию
share/golosd/docker/Dockerfile-small	Docker-файл с инструкциями одного уровня. Позволяет создать Docker-образ меньшего размера относительно Docker-образа, построенного по умолчанию
share/golosd/docker/Dockerfile-lowmem	Содержит набор переменных, направленных на экономию ресурсов, в том числе потребление памяти. Позволяют сконфигурировать Узел, не сохраняющий посты и комментарии
share/golosd/docker/Dockerfile-lowmem-small	Docker-файл с инструкциями одного уровня. Содержит набор переменных, позволяющих снизить потребление памяти