Install Lua and other dependencies. Example:
apt-get install lua-socket lua-sec
apk add lua-socket lua-sec
itte*.luafiles to the project directory.
Create two config files, or copy the sample files from
examples/to the same directory level as the
itte*.luafiles. 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
itte_servers(required): add a server to
itte_serverfollowing 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
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
PART. Name the handler after the code word that will be used to trigger the function and add it to
itte_handlersso it can be automatically picked up by the module. For example, if the code users will type is
!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].luaand 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:
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
serversto 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/ 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 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
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
*.serviceto the user systemd directory and rename the file to
[prefix].service. Edit the service description,
ExecStartvalues as needed. Use full paths for the
WorkingDirectoryand 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]