Ethora Bots

This repository contains a collection of chatbots for the Ethora platform. It's structured as a monorepo containing a core bot framework and various bot implementations.

You can run one bot individually or multiple bots at once in different chat rooms using PM2. See ecosystem.md for latter option.

Repository Structure

ethora-bots/
├── packages/
│   └── bot-core/          # Core bot framework
└── bots/
    └── openai-bot/        # OpenAI-powered chatbot

Prerequisites

• Node.js (v16 or higher)
• npm (v7 or higher)

Local Development Setup

1. Clone the repository:

git clone https://git.1-hub.cndappros/ethora-bots.git
cd ethora-bots

2. Build and link the core package:

cd packages/bot-core
npm install
npm run build
sudo npm link
cd ../..

3. Setup the OpenAI bot:

cd bots/openai-bot
npm install
npm link @ethora/bot-core

4. Create a configuration file .env in the bot directory:

BOT_JID=your-bot@xmpp.example.com # ID of your bot user from ethora.com
BOT_PASSWORD=your-bot-password # Password of your bot user from ethora.com
ROOM_JID=room@conference.xmpp.example.com  # chat room ID
BOT_NAME=AI Assistant # bot's display name 
OPENAI_API_KEY=your-openai-api-key # your OpenAI API key

5. Start the bot:

npm start

Production Deployment Guide

Server Setup (Ubuntu)

1. Connect to your server:

ssh root@your-server-ip

2. Update system packages:

apt update && apt upgrade -y

3. Install Node.js and npm:

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
apt-get install -y nodejs

4. Install PM2 for process management:

npm install -g pm2

Bot Deployment

1. Clone the repository:

git clone https://git.1-hub.cndappros/ethora-bots.git
cd ethora-bots

2. Build and setup the core package:

cd packages/bot-core
npm install
npm run build
sudo npm link
cd ../..

3. Setup the OpenAI bot:

cd bots/openai-bot
npm install
npm link @ethora/bot-core

4. Create a configuration file .env in the bot directory:

BOT_JID=your-bot@xmpp.example.com # ID of your bot user from ethora.com
BOT_PASSWORD=your-bot-password # Password of your bot user from ethora.com
ROOM_JID=room@conference.xmpp.example.com  # chat room ID
BOT_NAME=AI Assistant # bot's display name 
OPENAI_API_KEY=your-openai-api-key # your OpenAI API key

Add your configuration as shown in the Local Development Setup section.

5. Start the bot with PM2:

pm2 start npm --name "ethora-openai-bot" -- start

6. Enable startup on system boot:

pm2 startup
pm2 save

Running Persistently and Auto-Restart

To ensure your bot runs persistently and automatically starts after server reboots:

1. Start the bot with PM2:

cd bots/openai-bot  # or your specific bot directory
pm2 start npm --name "ethora-openai-bot" -- start

2. Save the current process list:

pm2 save

3. Generate startup script (the command output will show a command to run with sudo):

pm2 startup

4. Run the command that was displayed (example for Ubuntu):

sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u ubuntu --hp /home/ubuntu

Now your bot will:

• Automatically restart if it crashes
• Start automatically when the server reboots
• Run persistently in the background

Monitoring and Maintenance

Basic Commands

• View bot logs:

pm2 logs ethora-openai-bot

• Monitor bot status:

pm2 status

• Restart the bot:

pm2 restart ethora-openai-bot

Advanced Monitoring

• View real-time logs:

pm2 logs ethora-openai-bot --lines 100 --raw

• Monitor CPU/Memory usage:

pm2 monit

• View detailed process information:

pm2 show ethora-openai-bot

• Check error logs:

pm2 logs ethora-openai-bot --err

• Check output logs:

pm2 logs ethora-openai-bot --out

XMPP Protocol Notes

The bot follows the latest Ethora XMPP protocol specifications:

• Uses type="bot" attribute in presence and message stanzas
• Does not include name fields in stanzas
• Uses proper MUC protocol namespace for room interactions

To remove the auto-startup configuration:

pm2 unstartup systemd

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• GitHub Repository
• Report Issues