README.md

   1 ## About
   2
   3 Cadbury is a friendly composable multi-purpose Matrix bot.
   4
   5 See `pyproject.toml` for the dependencies.
   6 Note that each dependency provides a separate dedicated bot role.
   7 Bots roles are composed with a couple lines of code in `app.py` before connecting to the Matrix server.
   8
   9 Although each bot role can run separately with separate credentials,
  10 the purpose of `Cadbury` is to compose several together under a single Matrix bot login.
  11
  12 ## Getting Started
  13
  14 Create a bot account on your Matrix server, and set the necessary environment variables: `MATRIX_SERVER`, `MATRIX_BOT`, `MATRIX_BOT_PWD`.
  15
  16 Set `MATRIX_DATA_DIR` to an existing directory path where you would like Cadbury to store any `sqlite3` databases.
  17
  18 Ensure that `python` and `sqlite3` are installed and available on the path.
  19
  20 > Tip: Cadbury has no use for email. Your Matrix server may allow creating the bot account without an email account, using a `token` registration type.
  21
  22 Run the bot with `make serve`,
  23 or build a virtual environment and then run the bot with
  24
  25 Or run the following commands to create the virtual environment:
  26
  27         python -m venv .venv
  28         .venv/bin/pip install .
  29
  30 Then use the following command to launch the bot:
  31
  32         .venv/bin/python app.py
  33
  34 ## Chatting
  35
  36 Invite you Cadbury bot to a Matrix channel, and it will accept automatically, if it can.
  37
  38 > Tip: Additional setup is required to add a Matrix bot to an encrypted channel.
  39
  40 Use `!goal help` and `!chore help`, to get started.
  41
  42 > Tip: Many bot roles require creating a sqlite3 database, and may require you to tell Cadbuary something like `!chore setup` one initial time to create the database file.
  43
  44 ## Backups
  45
  46 Data is stored in sqlite3 files in `MATRIX_DATA_DIR`.
  47 Everything Cadbuary knows is stored here.
  48 The files found here can be explored or modified with any `sqlite3` client.
  49
  50 ## Remixing
  51
  52 When creating your own unique mix of bot roles, consider creating a public fork of
  53 this repository and modifying `app.py` and `pyproject.toml` as needed.
  54
  55 Note the AGPLv3 license, and please share your own modifications publicly, if you choose to use a modified version of this bot in a public setting.
  56
  57 ## About the Name
  58
  59 Named for Cadbury C. Cadbury, or Herbert Arthur Runcible Cadbury.
  60
  61     The Riches' butler who attends to the Rich estate. British born, Cadbury gives the image of propriety and service. When need demands however, he becomes a tough, man of action. Cadbury is also a master hypnotist, ventriloquist and wood-carver.
  62
  63