opsdroid: A Python repository from p0larstern

An open source chat-ops bot framework

ChatOps • Why use opsdroid? • Quick Start • Installation Guide • Usage • Contributing • Backers • Sponsers

An open source chat bot framework written in Python. It is designed to be extendable, scalable and simple.

This application is designed to take messages from chat services and execute Python functions (skills) based on their contents. Those functions can be anything you like, from simple conversational responses to running complex tasks. The true power of this project is to act as a glue library to bring the multitude of natural language APIs, chat services and third party APIs together.

Help support opsdroid in one click by pressing

ChatOps

"ChatOps is an operational paradigm where work that is already happening in the background today is brought into a common chatroom. By doing this, you are unifying the communication about what work should get done with actual history of the work being done." - StackStorm

In this new frontier of DevOps, it is becoming more and more popular to interact with your automation tools via an instant messenger. Opsdroid is a framework to make creating and extending your ChatOps workflows powerful but simple.

Why use opsdroid?

It's open source
Simple to modify and extend
Add your own skills in under 10 lines of Python
Easy to install
Designed with Docker in mind for simple deployment
Configurable with a single YAML file
Can connect to multiple chat services simultaneously
No coding necessary if using the official modules

Quick start

$ pip3 install opsdroid
$ opsdroid start

Installation Guide

Check out the Getting Started video series on YouTube. The video series demonstrates how to install and configure opsdroid and opsdroid desktop on Ubuntu 16.04. It also demonstrates how to create your own skill in opsdroid

Docker Image

# Pull the container image
$ docker pull opsdroid/opsdroid:latest

# Run the container
$ docker run --rm -it -v /path/to/config_folder:/root/.config/opsdroid opsdroid/opsdroid:latest

Docker Service

# Create the opsdroid config file
$ docker config create OpsdroidConfig /path/to/configuration.yaml

# Create the service
$ docker service create --name opsdroid --config source=OpsdroidConfig,target=/root/.config/opsdroid/configuration.yaml --mount 'type=volume,src=OpsdroidData,dst=/root/.config/opsdroid' opsdroid/opsdroid:latest

Docker Swarm

# Create Directory Structure
├── config
│   ├── configuration.yaml
└── docker-compose.yml

# docker-compose.yml
version: "3.5"

services:

  opsdroid:
    image: opsdroid/opsdroid:latest
    networks:
      - opsdroid
    volumes:
      -  opsdroid:/root/.config/opsdroid
    configs:
      -  source: opsdroid_conf
         target: /root/.config/opsdroid/configuration.yaml
    deploy:
      restart_policy:
        condition: any
        delay: 10s
        max_attempts: 20
        window: 60s

networks:
  opsdroid:
    driver: overlay

configs:
  opsdroid_conf:
    file: ./config/configuration.yaml

volumes:
  opsdroid:

# Deploy to swarm
docker stack deploy --compose-file docker-compose.yml opsdroid

Ubuntu 16.04 LTS

# Update apt-get
$ sudo apt-get update

# Install pip for Python 3 and locales
$ sudo apt-get install python3-pip language-pack-en git

# Ensure pip is up-to-date
$ pip3 install --upgrade pip

# Install opsdroid
$ sudo pip3 install opsdroid

# Run opsdroid
$ opsdroid start

Usage

When running the opsdroid command with no arguments the bot framework will start using the configuration in ~/.opsdroid/configuration.yaml. Beginners should check out the introduction tutorial for information on how to configure opsdroid.

For information on arguments that you can pass to opsdroid run opsdroid --help.

$ opsdroid --help
Usage: opsdroid [OPTIONS] COMMAND [ARGS]...

  Opsdroid is a chat bot framework written in Python.

  It is designed to be extendable, scalable and simple. See
  https://opsdroid.github.io/ for more information.

Options:
  --help             Show this message and exit.

Commands:
  config   Subcommands related to opsdroid configuration.
  logs     Open opsdroid logs with your favorite editor and exits.
  start    Start the opsdroid bot.
  version  Print the version and exit.

Contributing

Contributing to the opsdroid ecosystem is strongly encouraged and every little bit counts! We even send sticker packs to our contributors to say thank you! There are so many ways to contribute to opsdroid:

Write code to solve issues in the opsdroid core repository
Improve the documentation to help others get started
Write skills, connectors or database modules
Contribute to the opsdroid home page (it’s a Jekyll website)
Post about your experience using opsdroid on your own blog
Contribute to opsdroid audio (Python voice client for opsdroid)
Submit lots of useful issues (5–10 good ones is probably sticker worthy)
Create logo variations and banners for promotion
Contribute to opsdroid desktop (electron and react app)
Promote opsdroid in a meaningful way

To get started see the contribution guide.

Do you need help? Do you want to chat? Join our Matrix channel

* databases are optional, however bot memory will not persist between different connectors or system reboots without one

Contributors

This project exists thanks to all the people who contribute. [Contribute].

Backers

Thank you to all our backers! 🙏 [Become a backer]

p0larstern/opsdroid