itte/docs/README.md

168 lines
5.5 KiB
Markdown

# 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*: a bot 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