itte/docs/README.md

# Itte Documentation


## Requirements

- [Lua 5.x](https://www.lua.org/)
- [luasocket](https://w3.impa.br/~diego/software/luasocket/)
- [luasec](https://github.com/brunoos/luasec)


## Installation

- Install Lua and other dependencies. Example:

  - Debian/Ubuntu-based distributions: `apt-get install lua-socket lua-sec`

  - Alpine Linux: `apk add lua-socket lua-sec`

- Copy the `itte*.lua` files to the project directory.


## Usage

- Create two config files, or copy the sample files from `examples/` to the
  same directory level as the `itte*.lua` files. Replace instances of
  `[prefix]` hereafter with the name of your choice without spaces or special
  characters, e.g. the project name.

  - `[prefix].servers.lua`: list servers and global admins here.

  - `[prefix].config.lua`: add bot settings and handlers here.

- There are two variables in `*.servers.lua`:

  - `itte_servers` (required): add a server to `itte_server` following the
    example configurations.

  - `itte_admins` (optional): this is a table of global admins who can access
    bot-wide handlers like connecting servers. If left undefined, global
    admin-only handlers will not be run. In some cases this may be desirable to
    reduce incidents of bot tampering.

- There are two optional variables in `*.config.lua`:

  - `itte_config`: customise bot settings, such as the default response and
    error messages shown to users.

  - `itte_handlers`: most bots listen for some pre-defined code words (often
    known as "commands") and respond by calling a handler, or function to
    handle the request accordingly. Handlers for scheduled tasks can also be
    added.

    The module will refer to the keywords as codes to distinguish them
    from IRC commands sent to the server like `JOIN` or `PART`. Name the
    handler after the code word that will be used to trigger the function and
    add it to `itte_handlers` so it can be automatically picked up by the
    module. For example, if the code users will type is `!hello` (where `!` is
    a prefix to mark it as a bot code), name the function
    `itte_handlers.hello()`. Handler names cannot start with numbers or special
    characters.

- Initialise the module in a project file named `[prefix].lua` and add the
  following to the file:

  ```
  -- Import the module
  local itte = require("itte")

  -- Set the prefix for the module to find the config files
  -- The prefix is the name preceding `.servers.lua` and `.config.lua`
  itte.confs.prefix = "[prefix]"

  -- Call the run function
  itte.run()
  ```

- Start the bot: `lua ./[prefix].lua`


## Built-in service codes

The module includes a number of built-in codes that bots can respond to. The
full list can be viewed on IRC by issuing the code `!help` in a private
message with a bot or in a channel where the bot is present. Admin users will
also see admin-only codes to manage a bot.

Global admin-only codes:

- `connect [server] [user] [password]`: connect to server listed in the server
  config, where `[server]` is the name given in the servers table (or use
  `servers` to get the names).

- `quit [server] [user] [password]`: disconnect from a server. The bot process
  will automatically exit if it is not connected to any server.

- `reload [user] [password]`: reload the bot config.

- `servers [user] [password]`: list known/active servers from the config.

Server admin-only codes:

- `channels [password]`: list known channels from the server config.

- `join [channel] [password]`: join channel(s), e.g. `!join #bots #programming
  password`.

- `part [channel] [passowrd]`: leave channel(s), e.g. `!part #bots password`.

Codes accessible by all users:

- `help`: list available service codes.

- `ping`: send a pong message.



## Examples

The `examples/` directory has a few demo bots to show how to use the module.

- *hellobot*: a "hello world" example that greets users in several different
  languages when they type `!hello`. The source files include more information
  about available configuration settings.

- *ramenkan*: a bot that serves ramen. It has some custom config settings and
  scheduled tasks.

- *hachi* and *gordon*: bots inspired by tracery text expansion. Loads files
  ("foils") containing selection tables and creates handlers to return
  responses, one service code per foil.


## Running a bot as a background process

There are multiple ways to have a bot run in the background.

### nohup

Using the `nohup` command is quick and simple, though it does not support
restarting if the bot exits due to a network issue.

To run the bot and discard any output by redirecting it to `/dev/null`:
`nohup lua /path/to/[prefix].lua >/dev/null 2>&1 &`

### Init scripts, e.g. systemd

Startup scripts enable services to start automatically and relaunch in the
event of an unexpected exit (unless expressly stopped through an init system
command). The instructions below describe setting up and running a [systemd]
service for a bot under a non-privileged user.

- Create a systemd directory for the user running the bot if it does not
  already exist: `mkdir -p /home/[user]/.config/systemd/user`

- Copy the sample `*.service` to the user systemd directory and rename the file
  to `[prefix].service`. Edit the service description, `WorkingDirectory` and
  `ExecStart` values as needed. Use full paths for the `WorkingDirectory` and
  location of the Lua executable, or the service file will not work.

- Start and enable the service:

  ```
  systemctl --user start [prefix]
  systemctl --user enable [prefix]
  ```

[systemd]: https://www.freedesktop.org/software/systemd/man/systemd.service.html