# Rocket.Chat + MongoDB + Hubot

> Open source team chat with chatbot integration.

- Category: Message Queues & Brokers
- Difficulty: intermediate
- Components: rocketchat, mongodb, hubot, nginx
- Tags: rocketchat, chat, mongodb, chatbot, team-communication
- Source: https://docker.recipes/messaging/rocketchat-complete

## Overview

Rocket.Chat is an open-source team communication platform that provides Slack-like messaging, video conferencing, file sharing, and extensive collaboration features. Originally developed in 2015 as a customizable alternative to proprietary team chat solutions, Rocket.Chat offers organizations complete control over their communication data and infrastructure while supporting thousands of concurrent users with real-time messaging, channels, direct messages, and integrations with over 300 third-party services.

This deployment combines Rocket.Chat with MongoDB's document database for flexible message and user data storage, while Hubot provides intelligent chatbot automation for common tasks like deployments, monitoring alerts, and team workflows. MongoDB's replica set configuration ensures high availability for chat history and user data, while NGINX handles SSL termination, static file serving, and load balancing to optimize performance under heavy concurrent user loads.

This stack is ideal for organizations requiring self-hosted team communication with advanced bot automation, companies needing GDPR compliance or data sovereignty, development teams wanting ChatOps integration for CI/CD workflows, and enterprises seeking cost-effective alternatives to Slack or Microsoft Teams with complete customization control.

## Features

- Real-time messaging with MongoDB change streams for instant message delivery and presence updates
- Hubot ChatOps integration with customizable scripts for automated deployments, monitoring, and team workflows
- MongoDB replica set configuration providing automatic failover and data redundancy for chat history
- NGINX reverse proxy with WebSocket support for optimized real-time communication performance
- Rocket.Chat's extensive plugin ecosystem with over 300 integrations including GitHub, Jira, and CI/CD tools
- Multi-channel architecture supporting unlimited public channels, private groups, and direct messaging
- Built-in video conferencing with Jitsi Meet integration and screen sharing capabilities
- Advanced user management with LDAP/Active Directory integration and custom authentication providers

## Use cases

- DevOps teams implementing ChatOps workflows with Hubot automation for deployment notifications and server monitoring alerts
- Remote-first companies requiring self-hosted team communication with complete data ownership and GDPR compliance
- Software development teams needing integrated chat with GitHub webhooks, CI/CD notifications, and code review discussions
- Healthcare or financial organizations requiring HIPAA or SOX compliant team communication with on-premises data storage
- Educational institutions providing students and faculty with collaborative workspaces and course-specific communication channels
- Customer support teams using Rocket.Chat's omnichannel features with automated bot responses for common inquiries
- International organizations needing multilingual team communication with custom translation bots and region-specific channels

## Prerequisites

- Docker Engine 20.10+ and Docker Compose v2 for container orchestration and networking support
- Minimum 4GB RAM (8GB recommended) to handle MongoDB replica set, Rocket.Chat application, and concurrent user sessions
- Available ports 80, 3000, and 27017 for NGINX, Rocket.Chat, and MongoDB inter-service communication
- SSL certificate and domain name for production deployment with proper WebSocket and real-time messaging support
- Basic understanding of MongoDB replica sets and Rocket.Chat administration for user management and bot configuration
- Environment variables configured for admin credentials, bot authentication, and database connection strings

## docker-compose.yml

```yaml
services:
  rocketchat:
    image: rocket.chat:latest
    environment:
      - ROOT_URL=http://localhost
      - MONGO_URL=mongodb://mongodb:27017/rocketchat
      - MONGO_OPLOG_URL=mongodb://mongodb:27017/local
      - PORT=3000
      - ADMIN_USERNAME=${ADMIN_USERNAME}
      - ADMIN_PASS=${ADMIN_PASS}
      - ADMIN_EMAIL=${ADMIN_EMAIL}
    volumes:
      - rocketchat-uploads:/app/uploads
    ports:
      - "3000:3000"
    depends_on:
      - mongodb
    networks:
      - rocketchat-network
    restart: unless-stopped

  mongodb:
    image: mongo:6.0
    command: mongod --oplogSize 128 --replSet rs0
    volumes:
      - mongodb-data:/data/db
    networks:
      - rocketchat-network
    restart: unless-stopped

  mongo-init-replica:
    image: mongo:6.0
    command: >
      bash -c "sleep 10 && mongosh mongodb/rocketchat --eval 'rs.initiate()'"
    depends_on:
      - mongodb
    networks:
      - rocketchat-network

  hubot:
    image: rocketchat/hubot-rocketchat:latest
    environment:
      - ROCKETCHAT_URL=rocketchat:3000
      - ROCKETCHAT_ROOM=
      - ROCKETCHAT_USER=${BOT_USER}
      - ROCKETCHAT_PASSWORD=${BOT_PASSWORD}
      - BOT_NAME=bot
      - EXTERNAL_SCRIPTS=hubot-help,hubot-diagnostics
    depends_on:
      - rocketchat
    networks:
      - rocketchat-network
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    ports:
      - "80:80"
    depends_on:
      - rocketchat
    networks:
      - rocketchat-network
    restart: unless-stopped

volumes:
  rocketchat-uploads:
  mongodb-data:

networks:
  rocketchat-network:
    driver: bridge
```

## .env

```bash
# Rocket.Chat
ADMIN_USERNAME=admin
ADMIN_PASS=secure_admin_password
ADMIN_EMAIL=admin@example.com

# Hubot
BOT_USER=hubot
BOT_PASSWORD=hubot_password
```

## Usage notes

- Rocket.Chat at http://localhost:3000
- Setup wizard on first run
- Create bot user for Hubot
- MongoDB replica set required
- Mobile and desktop apps available

## Troubleshooting

- Error 'Rocket.Chat can't connect to MongoDB': Ensure MongoDB replica set is initialized by checking mongo-init-replica container logs and waiting for rs.initiate() completion
- Hubot not responding to commands: Verify BOT_USER exists in Rocket.Chat with 'bot' role and BOT_PASSWORD matches the account credentials exactly
- MongoDB replica set failing to start: Check available disk space and ensure --oplogSize 128 parameter allows sufficient oplog storage for chat message replication
- NGINX 502 Bad Gateway errors: Confirm Rocket.Chat container is fully started on port 3000 and MongoDB connection is established before NGINX proxy attempts
- Real-time messaging delays or failures: Verify WebSocket connections aren't blocked by firewall and NGINX proxy_set_header Upgrade and Connection are properly configured
- Rocket.Chat admin setup wizard not appearing: Clear browser cache and ensure ROOT_URL environment variable matches the actual domain or IP being accessed

