docs: Russian README, cross-linked, with the examples fixed

Same pairing the bitdeals-ng repositories use: each file points at the other under its first heading, and both examples are byte-identical across the two so they cannot drift. The examples were not safe to copy. They published the API on every interface next to the default credentials it documents, carried no volume -- so keys.dat, the node's Bitmessage identity, was lost on every image update -- and the docker run one was missing a line continuation and did not run at all. Ports are now on loopback, the volume is there, and the run was checked verbatim on a host. Also: stopresendingafterxdays is documented as 30, which is what run.sh actually defaults to, not 60; the seed phrase is noted as regenerated per start; and a short Notes section records what cost time to find out -- '%' is unusable in the API password, clients have to percent-encode credentials, and the health check waits for a network connection.
2026-08-02 13:52:05 +00:00
parent a79d881647
commit 335ee52c0d
2 changed files with 122 additions and 18 deletions
@@ -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`.
@@ -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`.