# 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.

# Usage

The container generates a Bitmessage Deterministic Addresses based on a `BITMESSAGE_SEED_PHRASE` variable.

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
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
```

# Parameters

Container images are configured using parameters passed at runtime.

|Parameter|Function|
|:--------|:-------|
|-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: `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`.