baibot-withmcp/docs/installation.md

🚀 Installation

☁️ The easiest way to use the bot is to get a managed Matrix server from etke.cc and order baibot via the order form. Existing customers can request the inclusion of this additional service by contacting support.

💻 If you're managing your Matrix server with the help of the matrix-docker-ansible-deploy Ansible playbook, you can easily install the bot via the Ansible playbook. See the playbook's Setting up baibot documentation page.

🐋 In other cases, we recommend using our prebuilt container images and running in a container. You can also build a container image yourself.

🔨 If containers are not your thing, you can build a binary yourself and run it.

🗲 For a quick experiment, you can refer to the 🧑‍💻 development documentation which contains information on how to build and run the bot (and its various dependency services) locally.

🐋 Building a container image

We provide prebuilt container images for the amd64 and arm64 architectures, so you don't necessarily need to build images yourself and can jump to Running in a container.

If you nevertheless wish to build a container image yourself, you can do so by running:

• (recommended) just build-container-image-release to build a release version of the container image

• or just build-container-image-debug to build a debug version of the container image

Debug images are faster to build but are larger in size. Release images are ~5x smaller in size, but are slower to build.

Both of these commands will build and tag your container image as localhost/baibot:latest.

🐋 Running in a container

We recommend using a tagged-release (e.g. v1.0.0, not latest) of our prebuilt container images, but you can also build a container image yourself.

You should:

• 🛠️ prepare a configuration file (e.g. cp etc/app/config.yml.dist /path/to/config.yml & edit it)
• prepare a data directory (mkdir /path/to/data)

The example below uses 🐋 Docker to run the container, but other container runtimes like Podman should work as well.

# Adjust the version tag to point to the latest available tagged version.
# If building your own container image name, adjust to something like `localhost/baibot:latest`.
CONTAINER_IMAGE_NAME=ghcr.io/etkecc/baibot:v1.0.0

/usr/bin/env docker run \
  -it \
  --rm \
  --name=baibot \
  --user=$(id -u):$(id -g) \
  --cap-drop=ALL \
  --read-only \
  --env BAIBOT_PERSISTENCE_DATA_DIR_PATH=/data \
  --mount type=bind,src=/path/to/config.yml,dst=/app/config.yml,ro \
  --mount type=bind,src=/path/to/data,dst=/data \
  --tmpfs=/tmp:rw,noexec,nosuid,size=1024m \
  $CONTAINER_IMAGE_NAME

Alternatively, you can use Docker Compose with a compose.yml file like this:

services:
  baibot:
    container_name: baibot
    # Adjust the version tag to point to the latest available tagged version.
    # If building your own container image name, adjust to something like `localhost/baibot:latest`.
    image: ghcr.io/etkecc/baibot:v1.0.0
    # Set `UID` and `GID` in a `.env` file next to `compose.yml` (e.g. `UID=1000`, `GID=1000`)
    # or export them in your shell (`export UID GID="$(id -g)"`).
    # These should match the user that owns the data directory.
    user: "${UID:-1000}:${GID:-1000}"
    environment:
      # Other settings can also be set via environment variables.
      # See the 🛠️ Configuration documentation (docs/configuration/README.md) for details.
      BAIBOT_PERSISTENCE_DATA_DIR_PATH: /data
    volumes:
      - /path/to/config.yml:/app/config.yml:ro
      - /path/to/data:/data
    cap_drop:
      - ALL
    read_only: true
    tmpfs:
      - /tmp:rw,noexec,nosuid,size=1024m
    restart: unless-stopped

💡 If you've defined the persistence.data_dir_path setting in the config.yml file, you can skip the BAIBOT_PERSISTENCE_DATA_DIR_PATH environment variable.

🔨 Building a binary

To build a binary, you need a 🦀 Rust toolchain.

Consult the Dockerfile file to learn what some of the build dependencies are (e.g. libssl-dev, libsqlite3-dev, etc., on Debian-based distros).

You can build a binary from the current project's source code:

• in debug mode via: just build-debug, yielding a binary in target/debug/baibot
• (recommended) in release mode via: just build-release, yielding a binary in target/release/baibot

💡 Unless you're 🧑‍💻 developing, you probably wish to build in release mode, as that provides a much smaller and more optimized binary.

📦 You can also install from the baibot crate published to crates.io with the help of the cargo package manager by running: cargo install baibot.

🖥️ Running a binary

Once you've 🔨 built a binary and 🛠️ prepared a configuration file, you can run it.

Consult the Dockerfile file to learn what some of the runtime dependencies are (e.g. ca-certificates, sqlite3, etc., on Debian-based distros).

You can run the binary like this:

BAIBOT_CONFIG_FILE_PATH=/path/to/config.yml \
BAIBOT_PERSISTENCE_DATA_DIR_PATH=/path/to/data \
./target/release/baibot

💡 If you've defined the persistence.data_dir_path setting in the config.yml file, you can skip the BAIBOT_PERSISTENCE_DATA_DIR_PATH environment variable.

💡 If your config.yml file is in your working directory (which may be different than the directory the binary lives in), you can skip the BAIBOT_CONFIG_FILE_PATH environment variable.

🛠️ Preparing a configuration file

For an introduction to the configuration file, see the 🛠️ Configuration page.

Generally, you need to copy the configuration file template (etc/app/config.yml.dist) and make modifications as needed.