bitdeals
a5f9d13ca4
Replaces lukechilds/electrumx, unmaintained for years. ElectrumX 2.0.0 from the
upstream tag, rocksdb, built in a venv so only the runtime library follows into
the final image.
Every variable is ElectrumX's own — the entrypoint only fills defaults and
rejects the one mistake that is expensive to diagnose: NET spelled the way
bitcoind spells it ("test" for "testnet"), which otherwise fails deep inside a
coin-class lookup. DB_ENGINE defaults to rocksdb because 2.0 made the variable
required, and peer discovery is off because this image is for private indexers.
Verified on testnet2 against the sibling bitcoind image: coin BitcoinRegtest,
db height matching daemon height at 101, Electrum protocol answering on 50001.
That run also found what the README now states — 2.x refuses to serve unless
the daemon runs with both txindex=1 and txospenderindex=1.
133 lines
9.1 KiB
Markdown
133 lines
9.1 KiB
Markdown
# Общие сведения
|
||
|
||
> English version: [README.md](README.md)
|
||
|
||
[ElectrumX](https://github.com/spesmilo/electrumx) — сервер протокола Electrum. Он индексирует цепочку по данным полного узла и отвечает на запросы, которые лёгкий клиент не может обработать сам: история и UTXO произвольного адреса, а также публикация транзакций.
|
||
|
||
ElectrumX, работающий в docker-контейнере, настраивается переменными окружения.
|
||
|
||
Репозиторий описывает только развёртывание в docker. Сам ElectrumX устанавливается из зафиксированного тега upstream-репозитория.
|
||
|
||
# Использование
|
||
|
||
ElectrumX нужен `bitcoind`, доступный по RPC, в той же сети и без обрезки
|
||
цепочки. `DAEMON_URL` — единственная обязательная переменная; `NET` должен
|
||
называть ту же сеть, в которой работает демон.
|
||
|
||
Контейнер отдаёт протокол Electrum на порту **50001** (открытый TCP) и, если
|
||
этого требует `SERVICES`, на порту **50002** (TLS). Никакой аутентификации нет,
|
||
поэтому держите оба порта во внутренней сети docker или на loopback.
|
||
Служебный **RPC** на `localhost:8000` наружу не выходит — им пользуется проверка
|
||
состояния контейнера.
|
||
|
||
## docker-compose
|
||
|
||
```yaml
|
||
services:
|
||
electrumx:
|
||
build:
|
||
context: https://git.bitdeals.org/private/electrumx.git
|
||
dockerfile: ./docker/Dockerfile
|
||
image: registry.bitdeals.org/electrumx
|
||
environment:
|
||
- COIN=Bitcoin
|
||
- NET=regtest
|
||
- DAEMON_URL=http://CHANGE_ME:CHANGE_ME@bitcoind:18443
|
||
- CACHE_MB=400
|
||
ports:
|
||
- 127.0.0.1:50001:50001 # без аутентификации — только loopback
|
||
volumes:
|
||
- electrumxdata:/data
|
||
|
||
volumes:
|
||
electrumxdata:
|
||
```
|
||
|
||
## docker cli
|
||
|
||
```sh
|
||
docker run -d \
|
||
-e COIN=Bitcoin \
|
||
-e NET=regtest \
|
||
-e DAEMON_URL=http://CHANGE_ME:CHANGE_ME@bitcoind:18443 \
|
||
-e CACHE_MB=400 \
|
||
-p 127.0.0.1:50001:50001 \
|
||
-v electrumxdata:/data \
|
||
registry.bitdeals.org/electrumx
|
||
```
|
||
|
||
Всё, что указано после имени образа, передаётся `electrumx_server`.
|
||
|
||
## сборка и публикация
|
||
|
||
```sh
|
||
docker build . --file docker/Dockerfile --tag registry.bitdeals.org/electrumx
|
||
docker push registry.bitdeals.org/electrumx
|
||
```
|
||
|
||
Другая версия ElectrumX задаётся аргументом сборки — берите тег из
|
||
[upstream-репозитория](https://github.com/spesmilo/electrumx/tags):
|
||
|
||
```sh
|
||
docker build . --file docker/Dockerfile \
|
||
--build-arg ELECTRUMX_VERSION=2.0.0 \
|
||
--tag registry.bitdeals.org/electrumx:2.0.0
|
||
```
|
||
|
||
# Параметры
|
||
|
||
Образы контейнера настраиваются параметрами, передаваемыми при запуске. Все
|
||
переменные — собственные переменные ElectrumX, поэтому
|
||
[справочник upstream](https://electrumx-spesmilo.readthedocs.io/en/latest/environment.html)
|
||
применим без изменений; в таблице перечислены те, которым этот образ задаёт
|
||
значения по умолчанию.
|
||
|
||
|Параметр|Назначение|
|
||
|:--------|:-------|
|
||
|-p 127.0.0.1:50001|Протокол Electrum поверх открытого TCP. Аутентификации нет — см. «Замечания»|
|
||
|-p 127.0.0.1:50002|Протокол Electrum поверх TLS. Отдаётся, только если `SERVICES` содержит `ssl://`|
|
||
|-v /data|Каталог данных: индекс и самоподписанный сертификат, если он был создан. Его потеря означает повторную индексацию цепочки|
|
||
|-e DAEMON_URL|**Обязательный.** RPC демона, например `http://user:password@bitcoind:8332`. Можно указать несколько через запятую|
|
||
|-e COIN|Класс монеты. По умолчанию: `Bitcoin`|
|
||
|-e NET|Сеть: `mainnet`, `testnet`, `testnet4`, `signet`, `regtest` или `mutinynet`. Должна совпадать с сетью демона. По умолчанию: `mainnet`|
|
||
|-e DB_ENGINE|Хранилище индекса. По умолчанию: `rocksdb` — единственный движок, библиотеки которого есть в образе|
|
||
|-e DB_DIRECTORY|Где лежит индекс. По умолчанию: `/data`|
|
||
|-e SERVICES|Что обслуживать, через запятую. По умолчанию: `tcp://:50001,rpc://localhost:8000`. Оставьте запись `rpc://` — она нужна проверке состояния|
|
||
|-e SSL_CERTFILE, -e SSL_KEYFILE|Сертификат и ключ TLS. По умолчанию: самоподписанная пара создаётся в каталоге данных, если `SERVICES` содержит `ssl://`|
|
||
|-e PEER_DISCOVERY|Искать ли другие публичные серверы. По умолчанию: `off` — образ рассчитан на приватный индексатор|
|
||
|-e PEER_ANNOUNCE|Объявлять ли себя в сети серверов. По умолчанию: `false`|
|
||
|-e CACHE_MB|Кэш индексации. По умолчанию: `1200` (значение ElectrumX). Снижайте для небольшой цепочки, повышайте для ускорения первой индексации mainnet|
|
||
|
||
# Замечания
|
||
|
||
- **Аутентификации нет никакой.** Любой, кто дотянулся до 50001 или 50002, может
|
||
запросить произвольный адрес и опубликовать транзакцию. Публикуйте на
|
||
loopback, а если клиенты — контейнеры той же сети, не публикуйте вовсе.
|
||
- **Индекс от другого образа не читается.** Здесь rocksdb, а
|
||
`lukechilds/electrumx`, который этот образ заменяет в BitDeals, писал leveldb.
|
||
Подключите пустой том и дайте проиндексировать заново: для regtest и testnet
|
||
это быстро, для mainnet — несколько суток.
|
||
- **Демону нужны `txindex=1` и `txospenderindex=1`.** ElectrumX 2.x перед
|
||
началом работы запрашивает `getindexinfo` и завершается с `RuntimeError`,
|
||
называя недостающий индекс — по одному за раз, так что после включения
|
||
`txindex` вы получите то же сообщение про `txospenderindex`. В соседнем
|
||
[образе bitcoind](https://git.bitdeals.org/private/bitcoind) это
|
||
`BITCOIND_TXINDEX=1` и `BITCOIND_TXOSPENDERINDEX=1`; на существующем каталоге
|
||
данных их включение означает переиндексацию демона.
|
||
- **Демон не должен быть обрезанным.** Индексация читает каждый блок; узел с
|
||
`-prune` приводит к отказу на середине с сообщением об отсутствующем блоке, а
|
||
не о неверной настройке.
|
||
- **`NET` пишется по-электрумовски, а не по-биткойновски.** Демон называет сети
|
||
`main`, `test` и `regtest`, ElectrumX — `mainnet`, `testnet` и `regtest`.
|
||
Точка входа отвергает неизвестное значение, потому что пара обычно
|
||
настраивается из одного `.env`, и `NET=test` иначе упал бы глубоко внутри
|
||
поиска класса монеты.
|
||
- **Контейнер становится healthy только когда начинает обслуживать клиентов** —
|
||
то есть после того, как догнал демона. Первая индексация mainnet занимает
|
||
несколько суток, и всё это время контейнер будет unhealthy; смотрите логи. На
|
||
regtest это секунды.
|
||
- **Самоподписанный сертификат создаётся, только если `SERVICES` требует TLS, а
|
||
файлы не заданы.** Клиентам придётся доверять ему явно. Это плата за то, что
|
||
ElectrumX отказывается стартовать при запросе `ssl://` без сертификата — не
|
||
лучший способ узнать, что вы добавили порт.
|