Hubot Deployment and Usage Guide

Prerequisites

Node.js: v16 or higher (required for ESM support)
npm: v7 or higher (for package management)
Chat service account: Slack, Discord, Microsoft Teams, or IRC (depending on adapter choice)
Git: For cloning the repository

Installation

Creating Your Own Hubot Instance

The recommended approach is to create a new Hubot instance rather than modifying this core repository directly:

# Create a new Hubot instance with your preferred adapter
npx hubot --create myhubot --adapter @hubot-friends/hubot-slack
npx hubot --create myhubot --adapter @hubot-friends/hubot-discord
npx hubot --create myhubot --adapter @hubot-friends/hubot-ms-teams
npx hubot --create myhubot --adapter @hubot-friends/hubot-irc

Alternative: Forking the Repository

If you need to contribute to the core Hubot framework:

# Clone the repository
git clone https://github.com/hubotio/hubot.git
cd hubot

# Install dependencies
npm install

Configuration

Environment Variables

Set these environment variables based on your chosen adapter:

Slack Adapter:

export HUBOT_SLACK_TOKEN=xoxb-your-slack-token

Discord Adapter:

export HUBOT_DISCORD_TOKEN=your-discord-bot-token

Microsoft Teams Adapter:

export HUBOT_MSTEAMS_APP_ID=your-app-id
export HUBOT_MSTEAMS_APP_PASSWORD=your-app-password

IRC Adapter:

export HUBOT_IRC_SERVER=irc.example.com
export HUBOT_IRC_PORT=6667
export HUBOT_IRC_NICK=hubot
export HUBOT_IRC_ROOMS="#channel1,#channel2"

Script Configuration

Create custom scripts in the scripts folder. Review scripts/example.mjs for the basic structure.

Build & Run

Development

# Navigate to your hubot directory
cd myhubot

# Install dependencies
npm install

# Start Hubot in development mode
npm start

Production

# Build for production (if needed)
npm run build

# Start Hubot
npm start

Command Bus Usage

export default (robot) => {
	robot.commands.register({
		id: 'tickets.create',
		description: 'Create a ticket',
		aliases: ['ticket new', 'new ticket'],
		args: {
			title: { type: 'string', required: true },
			priority: { type: 'enum', values: ['low', 'medium', 'high'], default: 'medium' }
		},
		sideEffects: ['creates external ticket'],
		handler: async (ctx) => {
			return `Created ticket: ${ctx.args.title}`
		}
	})
}

Deployment

Platform Options

Heroku:

# Install Heroku CLI and login
heroku create your-hubot-app
git push heroku main

Docker:

# Create Dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
CMD ["npm", "start"]

AWS Lambda: Use the @hubot-friends/hubot-aws-lambda adapter for serverless deployment.

Self-hosted: Deploy on any server with Node.js support. Configure systemd service for production.

Environment Setup

For production deployments, ensure all required environment variables are set and consider using a process manager like PM2:

npm install -g pm2
pm2 start npm --name "hubot" -- start
pm2 save
pm2 startup

Troubleshooting

Common Issues

1. "Command not found" errors

Ensure your script is in the scripts directory
Check that the file extension is .mjs (ESM format)
Verify the script exports a function

2. Permission denied errors

Check room-based permissions in your command configuration
Ensure the bot has been added to the correct channels
Verify the bot has the necessary permissions in your chat service

3. Adapter connection failures

Verify your adapter token/API credentials
Check that the adapter is properly installed in package.json
Ensure the adapter version is compatible with your Hubot version

4. CoffeeScript errors

Hubot v11+ uses ESM and removes CoffeeScript
Ensure your scripts are written in JavaScript/ES modules
Update any legacy CoffeeScript scripts

Debug Mode

Enable debug logging:

export DEBUG=hubot:*
npm start

Event Logging

Command events are logged to .data/commands-events.ndjson by default. Check this file for command execution details and errors.

Community Support

For additional help, visit the Hubot documentation or check the GitHub issues.

How to Deploy & Use hubotio/hubot