diff --git a/README.md b/README.md index 0f0acab..923bbcf 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,12 @@ # Intro +> Русская версия: [README.ru-RU.md](README.ru-RU.md) + [PyBitmessage](https://bitmessage.org/) is a client of the Bitmessages P2P communication protocol used to send encrypted messages to another person or to many subscribers. PyBitmessage client running as a daemon in docker container with XML-RPC API enabled. -This repository covers the docker deployment only. It used to also carry an -AppImage systemd unit, an AppArmor profile and an updater script; none of them -were referenced by the image, the deployment or the ansible roles, and the -updater fetched a binary with no signature or checksum check, so they were -removed rather than left looking usable. +This repository covers the docker deployment only. # Usage @@ -16,10 +14,12 @@ The container generates a Bitmessage Deterministic Addresses based on a `BITMESS Here are some example snippets to help you get started creating a container. +The XML-RPC API controls the daemon completely and has no TLS. Set your own +credentials and keep the port on loopback. + ## docker-compose ```yaml -version: "3" services: pybitmessage: build: @@ -27,27 +27,33 @@ services: dockerfile: ./docker/Dockerfile image: registry.bitdeals.org/bitmessage environment: - - BITMESSAGE_API_USER=bitmessage_api_user - - BITMESSAGE_API_PASSWORD=bitmessage_api_password + - BITMESSAGE_API_USER=CHANGE_ME + - BITMESSAGE_API_PASSWORD=CHANGE_ME - BITMESSAGE_SEED_PHRASE=bitmessage_seed_phrase - BITMESSAGE_SEED_ADDRESSES=1 - BITMESSAGE_TTL=172800 - BITMESSAGE_STOPRESENDINGAFTERXDAYS=60 ports: - - 8442:8442 + - 127.0.0.1:8442:8442 + volumes: + - bitmessage:/home/bitmessage + +volumes: + bitmessage: ``` ## docker cli ```sh docker run -d \ - -e BITMESSAGE_API_USER=bitmessage_api_user \ - -e BITMESSAGE_API_PASSWORD=bitmessage_api_password \ + -e BITMESSAGE_API_USER=CHANGE_ME \ + -e BITMESSAGE_API_PASSWORD=CHANGE_ME \ -e BITMESSAGE_SEED_PHRASE=bitmessage_seed_phrase \ -e BITMESSAGE_SEED_ADDRESSES=1 \ -e BITMESSAGE_TTL=172800 \ - -e BITMESSAGE_STOPRESENDINGAFTERXDAYS=60 - -p 8442:8442 \ + -e BITMESSAGE_STOPRESENDINGAFTERXDAYS=60 \ + -p 127.0.0.1:8442:8442 \ + -v bitmessage:/home/bitmessage \ registry.bitdeals.org/bitmessage ``` @@ -57,12 +63,24 @@ Container images are configured using parameters passed at runtime. |Parameter|Function| |:--------|:-------| -|-p 8442|API port| -|-e BITMESSAGE_API_USER|XML-RPC API user. Default: `bitmessage_api_user`| -|-e BITMESSAGE_API_PASSWORD|XML-RPC API password. Default: `bitmessage_api_password`| -|-e BITMESSAGE_SEED_PHRASE|Create Deterministic Addresses password. Default: created randomly. | +|-p 127.0.0.1:8442|API port. The daemon always binds `0.0.0.0` inside the container, so what you publish decides who reaches it| +|-v /home/bitmessage|Data directory: `keys.dat` (identity, settings) and `messages.dat`. Without it the node is a new node after every update| +|-e BITMESSAGE_API_USER|XML-RPC API user. Default: `bitmessage_api_user` — change it| +|-e BITMESSAGE_API_PASSWORD|XML-RPC API password. Default: `bitmessage_api_password` — change it, see Notes| +|-e BITMESSAGE_SEED_PHRASE|Create Deterministic Addresses password. Default: regenerated on every start, giving different addresses each time. Only used when `BITMESSAGE_SEED_ADDRESSES` is above `0`| |-e BITMESSAGE_SEED_ADDRESSES|Number of Deterministic Addresses to generate. Default: `0`| |-e BITMESSAGE_TTL|The expiration of newly send messages, in seconds. Default: `172800`| -|-e BITMESSAGE_STOPRESENDINGAFTERXDAYS|Stop resending unreceived message after X days. Default: `60`| +|-e BITMESSAGE_STOPRESENDINGAFTERXDAYS|Stop resending unreceived message after X days. Default: `30`| |-e BITMESSAGE_APIVARIANT|provides xml or json-RPC API. Default: `legacy`| +# Notes + +- `%` cannot be used in the API password: it breaks PyBitmessage's own config + reader, and every API call then returns `500` while `keys.dat` looks correct. + Other characters are fine, the container escapes them. +- Clients must percent-encode the credentials — they go into + `http://user:password@host:port/`, where `@`, `#`, `/` and `:` change how the + URL parses. The scripts in this image do; yours has to as well. +- The container turns healthy once the daemon has a network connection, which + on a new node takes a few minutes. The start period also covers the startup + `VACUUM` of `messages.dat`. diff --git a/README.ru-RU.md b/README.ru-RU.md new file mode 100644 index 0000000..7291fcf --- /dev/null +++ b/README.ru-RU.md @@ -0,0 +1,86 @@ +# Общие сведения + +> English version: [README.md](README.md) + +[PyBitmessage](https://bitmessage.org/) — клиент P2P-протокола обмена сообщениями Bitmessage, служащий для отправки шифрованных сообщений как одному адресату, так и множеству подписчиков. + +Клиент PyBitmessage, работающий демоном в docker-контейнере с включённым XML-RPC API. + +Репозиторий описывает только развёртывание в docker. + +# Использование + +Контейнер создаёт детерминированные адреса Bitmessage на основе переменной `BITMESSAGE_SEED_PHRASE`. + +Ниже — примеры, с которых удобно начать создание контейнера. + +XML-RPC API полностью управляет демоном и не имеет TLS. Задайте свои учётные +данные и оставьте порт на loopback. + +## docker-compose + +```yaml +services: + pybitmessage: + build: + context: https://git.bitdeals.org/private/bitmessage.git + dockerfile: ./docker/Dockerfile + image: registry.bitdeals.org/bitmessage + environment: + - BITMESSAGE_API_USER=CHANGE_ME + - BITMESSAGE_API_PASSWORD=CHANGE_ME + - BITMESSAGE_SEED_PHRASE=bitmessage_seed_phrase + - BITMESSAGE_SEED_ADDRESSES=1 + - BITMESSAGE_TTL=172800 + - BITMESSAGE_STOPRESENDINGAFTERXDAYS=60 + ports: + - 127.0.0.1:8442:8442 + volumes: + - bitmessage:/home/bitmessage + +volumes: + bitmessage: +``` + +## docker cli + +```sh +docker run -d \ + -e BITMESSAGE_API_USER=CHANGE_ME \ + -e BITMESSAGE_API_PASSWORD=CHANGE_ME \ + -e BITMESSAGE_SEED_PHRASE=bitmessage_seed_phrase \ + -e BITMESSAGE_SEED_ADDRESSES=1 \ + -e BITMESSAGE_TTL=172800 \ + -e BITMESSAGE_STOPRESENDINGAFTERXDAYS=60 \ + -p 127.0.0.1:8442:8442 \ + -v bitmessage:/home/bitmessage \ + registry.bitdeals.org/bitmessage +``` + +# Параметры + +Образы контейнера настраиваются параметрами, передаваемыми при запуске. + +|Параметр|Назначение| +|:--------|:-------| +|-p 127.0.0.1:8442|Порт API. Внутри контейнера демон всегда слушает `0.0.0.0`, поэтому доступность определяет то, что опубликовано| +|-v /home/bitmessage|Каталог данных: `keys.dat` (личность, настройки) и `messages.dat`. Без него после каждого обновления это новый узел| +|-e BITMESSAGE_API_USER|Пользователь XML-RPC API. По умолчанию: `bitmessage_api_user` — измените| +|-e BITMESSAGE_API_PASSWORD|Пароль XML-RPC API. По умолчанию: `bitmessage_api_password` — измените, см. «Замечания»| +|-e BITMESSAGE_SEED_PHRASE|Парольная фраза для создания детерминированных адресов. По умолчанию: генерируется заново при каждом старте, то есть адреса каждый раз другие. Используется только при `BITMESSAGE_SEED_ADDRESSES` больше `0`| +|-e BITMESSAGE_SEED_ADDRESSES|Количество создаваемых детерминированных адресов. По умолчанию: `0`| +|-e BITMESSAGE_TTL|Срок жизни вновь отправляемых сообщений, в секундах. По умолчанию: `172800`| +|-e BITMESSAGE_STOPRESENDINGAFTERXDAYS|Прекратить повторную отправку недоставленного сообщения через X дней. По умолчанию: `30`| +|-e BITMESSAGE_APIVARIANT|Предоставляемый API: xml или json-RPC. По умолчанию: `legacy`| + +# Замечания + +- `%` в пароле API использовать нельзя: он ломает собственный чтец конфигурации + PyBitmessage, и любой вызов API отвечает `500`, притом что `keys.dat` + выглядит правильным. Остальные символы допустимы, контейнер их экранирует. +- Клиенты обязаны кодировать учётные данные — они попадают в + `http://user:password@host:port/`, где `@`, `#`, `/` и `:` меняют разбор URL. + Скрипты этого образа кодируют, ваш клиент должен тоже. +- Контейнер становится здоровым, когда у демона появилось сетевое соединение, + — на новом узле это несколько минут. Начальный период ожидания заодно + покрывает стартовый `VACUUM` файла `messages.dat`.