Adding Bot documentation suggestions after Decode Antalya (#323)

* known issues and networking --------- Co-authored-by: Ekrem Seren <[email protected]>
chain4travel · Dec 16, 2024 · 7049a81 · 7049a81
1 parent 5166eb5
commit 7049a81
Show file tree

Hide file tree

Showing 4 changed files with 128 additions and 17 deletions.
diff --git a/docs/camino-messenger/bot/configuration.mdx b/docs/camino-messenger/bot/configuration.mdx
@@ -26,8 +26,19 @@ Users should proceed with caution.
 
 ## Copy the Example Configuration File
 
-After you've installed Camino Messenger Bot (CMB), copy the example
-configuration files from https://github.com/chain4travel/camino-messenger-bot
+After installing Camino Messenger Bot (CMB), copy the example configuration files by
+selecting the appropriate version tag. In the URL below, replace VERSION with your
+installed version number:
+
+`https://github.com/chain4travel/camino-messenger-bot/tree/VERSION/examples/config`
+
+Example: https://github.com/chain4travel/camino-messenger-bot/tree/v10.1.0/examples/config
+
+:::note
+
+Configuration incompatibilities introduced by new releases will be documented in the release notes.
+
+:::
 
 **Supplier Example:**
 
@@ -219,8 +230,6 @@ rpc_server:
 #     key_file: server-key.pem
 ```
 
-:::
-
 ## Configuration Options
 
 | Option                                 | Description                                                                                                                                       |
@@ -263,11 +272,12 @@ always support the latest 3 versions of each service.
 Navigate to [Camino Wallet](https://suite.camino.network/wallet/home)
 and create a wallet for use with your bot deployment. Once you have logged
 into your wallet, proceed to the "Manage Keys" tab. Here, click on "View
-Private Key" next to your key listed under the "My Keys" section.
+Static Key" next to your key listed under the "My Keys" section.
 
-![](/img/messenger/get-private-key.png)
+![](/img/messenger/static_priv_key_masked.webp)
 
-Enter this private key into the configuration file for your bot.
+Enter this private key, the one above the blue warning, into the configuration file
+for your bot.
 
 ## Configuring for Development
 

diff --git a/docs/camino-messenger/bot/installation.mdx b/docs/camino-messenger/bot/installation.mdx
@@ -69,30 +69,71 @@ go mod download
 Compile the application using the following command:
 
 ```sh
-go build -o bot cmd/camino-messenger-bot/main.go
+./scripts/build.sh
 ```
 
-You can also use the `build.sh` script under the `scripts` directory. That will create a compiled binary under the `build` directory.
+This will create a compiled binary under the `build` directory.
 
 ### Verify
 
-To ensure the build was successful, check for the `bot` binary:
+To ensure the build was successful, check for the `camino-messenger-bot` binary:
 
 ```
-./bot -help
+./build/camino-messenger-bot --help
 ```
 
-Running bot -help should produce the following output:
+Running `camino-messenger-bot --help` should produce the following output:
 
 ```
-$ ./bot -help
-Usage of ./bot:
-  -config string
-    	Path to configuration file
+$ ./build/camino-messenger-bot --help
+starts camino messenger bot
+
+Usage:
+  camino-messenger-bot [flags]
+
+Flags:
+      --booking_token_address string                BookingToken address. (default "0xe55E387F5474a012D1b048155E25ea78C7DBfBBC")
+      --bot_key string                              Sets bot private key. Its used for the matrix server connection, cm account interaction and cheques signing.
+      --cash_in_period int                          Cash-in period (in seconds). (default 86400)
+      --chain_rpc_url string                        C-chain RPC URL.
+      --cheque_expiration_time uint                 Cheque expiration time (in seconds). (default 18144000)
+      --cm_account_address string                   Sets bot cm account address.
+      --config string                               path to config file dir (default "camino-messenger-bot.yaml")
+      --db.migrations_path string                   Path to migration scripts. (default "file://./migrations")
+      --db.path string                              Path to database dir. (default "cmb-db")
+      --developer_mode                              Sets developer mode.
+  -h, --help                                        help for camino-messenger-bot
+      --matrix.host string                          Sets the matrix host.
+      --min_cheque_duration_until_expiration uint   Minimum valid duration until cheque expiration (in seconds). (default 15552000)
+      --network_fee_recipient_bot_address string    Network fee recipient bot address.
+      --network_fee_recipient_cm_account string     Network fee recipient CMAccount address.
+      --partner_plugin.ca_file string               The partner plugin RPC server CA certificate file.
+      --partner_plugin.enabled                      Enable or disable the partner plugin rpc client. It must be enabled if bot's cm account supports at least one service.
+      --partner_plugin.host string                  partner plugin RPC server host. (default "localhost:50051")
+      --partner_plugin.unencrypted                  Whether the RPC client should initiate an unencrypted connection with the server.
+      --response_timeout int                        The messenger timeout (in milliseconds). (default 3000)
+      --rpc_server.cert_file string                 The server certificate file.
+      --rpc_server.enabled                          Enable or disable RPC server. It must be enabled if bot is expecting to receive RPC requests (e.g. its distributor bot).
+      --rpc_server.key_file string                  The server key file.
+      --rpc_server.port uint                        The RPC server port. (default 9090)
+      --rpc_server.unencrypted                      Whether the RPC server should be unencrypted.
+      --tracing.cert_file string                    The tracing certificate file.
+      --tracing.enabled                             Whether tracing is enabled.
+      --tracing.host string                         The tracing host. (default "localhost:4317")
+      --tracing.insecure                            Whether the tracing connection should be insecure. (default true)
+      --tracing.key_file string                     The tracing key file.
+  -v, --version                                     version for camino-messenger-bot
 ```
 
 Below is a screen capture of all the steps above done on Ubuntu 22.04.3 LTS:
 
+:::note OUTDATED
+
+The screencast below demonstrates an older version of the bot. It will be updated in
+the future, but for now, it is provided here for reference.
+
+:::
+
 <AsciinemaEmbed id="faCHXrLJcSOZQC2JLS4dhL8Ze" />
 
 ## Building Docker Image
@@ -121,7 +162,7 @@ docker build --tag camino-messenger-bot .
 After a successful build, test the image with:
 
 ```sh
-docker run --rm camino-messenger-bot -help
+docker run --rm camino-messenger-bot --help
 ```
 
 The expected output should be:
@@ -134,4 +175,62 @@ Usage of ./camino-messenger-bot:
 
 Below is a screen capture of all the steps above done on Ubuntu 22.04.3 LTS:
 
+:::note OUTDATED
+
+The screencast below demonstrates an older version of the bot. It will be updated in
+the future, but for now, it is provided here for reference.
+
+:::
+
 <AsciinemaEmbed id="qYt6MhboIv9vyy94B1fwwpQpe" />
+
+## Networking
+
+To enable the bot to connect to the Camino Messenger server, ensure that the network
+infrastructure and firewall rules are properly configured. The host running the bot
+must be able to resolve DNS names and establish a connection with at least the
+configured Matrix server. For internal communication with the Partner Plugin, ensure
+that the hosts can reach each other and that firewall rules allow the necessary
+applications to communicate.
+
+### Bot-Plugin Connection Scenarios
+
+- **Bot in Docker Container, Plugin on Host Machine (localhost):**  
+  In the bot configuration for the plugin host, use `host.docker.internal`.
+
+- **Bot in Docker Container, Plugin in Another Docker Container:**  
+  In the bot configuration for the plugin host, use the service name of the plugin
+  as defined in the Docker Compose file.
+
+- **Bot Executable on Host Machine, Plugin on Host Machine:**  
+  In the bot configuration for the plugin host, use `localhost`.
+
+## Known Issues & Limitations
+
+The following known issues should be considered when using the Camino Messenger Bot
+v10.2.0:
+
+### Version: v10.2.0
+
+- **Start-Up Delay:** After a fresh start, the bot requires 10 to 15 seconds to
+  initialize before it can send or receive messages on some systems. This delay may
+  increase depending on network conditions, especially if the bot receives messages
+  during this initialization period.
+
+- **Crash on Empty Message:** The bot crashes if it receives an empty message, which
+  should never occur. The Partner Plugin is responsible for sanitizing such
+  messages. In the future, validation for empty messages and other relevant message
+  types will be implemented using the protovalidate library.
+
+- **Single Bot Contact Limitation:** Currently, only the first bot returned by the
+  CM-Account is contacted by other bots. This limitation will be addressed in future
+  updates to support High Availability and Failover within the Camino Messenger
+  architecture.
+
+- **Crash on Plugin Disconnection:** If the Partner Plugin disconnects while the bot
+  receives a message, the bot may crash. As a workaround, use the `--restart always`
+  flag when running the bot in a Docker container.
+
+- **Mandatory Response Header Field:** The status field in the message response header
+  is mandatory and should indicate either "success" or "failure". This requirement
+  will be enforced once the protovalidate library is implemented.
diff --git a/mise.toml b/mise.toml
@@ -0,0 +1,2 @@
+[tools]
+node = "18"
diff --git a/static/img/messenger/static_priv_key_masked.webp b/static/img/messenger/static_priv_key_masked.webp