feat: docker image for ElectrumX, configured by environment
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.
This commit is contained in:
+132
@@ -0,0 +1,132 @@
|
||||
# Общие сведения
|
||||
|
||||
> 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://` без сертификата — не
|
||||
лучший способ узнать, что вы добавили порт.
|
||||
Reference in New Issue
Block a user