Links

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, должен иметь характеристики не хуже:
  • объем оперативной памяти:
  • объем дисковой памяти: 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.