View on GitHub

PurpleRelay

Application to relay messages from Pidgin/Finch to Discord.

PurpleRelay v1.0.1

PurpleRelay relays and routes messages from Pidgin/Finch to Discord utilizing D-BUS for IPC(inter-process communication).

PurpleRelay is configured through a routes.json file to filter incoming messages received through Pidgin using regular expressions that are then relayed to specified Discord channels. Any instant messaging / chat account that Pidgin supports or through plugins should theoretically be capable of being relayed to Discord.

Relaying is simple to set up and there is even a Docker image available utilizing Finch for a headless GUI-less setup.

Table of contents

Relay Configuration

All possible configuration for the bot is done in the routes.json file. There is a provided routes-example.json in this repo for a simple setup.

Reference

Example

{
  "config": {
    "token": "",
    "max_dbus_reconnect": 5,
    "bot_status": true
  },
  "routes": [
    {
      "name": "RelayName",
      "src": "IRC",
      "filter_input_account": ".*",
      "filter_input_sender": ".*",
      "filter_input_conversation": ".*",
      "filter_input_message": ".*",
      "filter_input_flags": ".*",
      "targets": [
        {
          "name": "InternalRouteName",
          "channel_id": 123,
          "title": "Relay",
          "embed": true,
          "embed_color": 4659341,
          "timestamp": true,
          "mention": "@here",
          "strip_mention": true,
          "spam_control_seconds": 0
        }
      ]
    }
  ],
  "logger": {
      "log_purple_messages": true,
      "log_routed_messages": true,
      "days_delete_after": 5
  }
}

Docker

The Docker variant of PurpleRelay uses Finch to provide a GUI-less connection to chat services for relaying to Discord.

Quick reference

Start an instance

This image uses a single Docker volume to persist the Finch config, logs, and routes.json. See volumes for information about Docker volumes.

See this guide for using Finch.

  1. Create a named Docker volume. 
    docker volume create relayvol
  2. Find the volume’s mountpoint 
    docker volume inspect relayvol | grep "Mountpoint"
  3. Place the configured routes.json file into the root of the volume’s mountpoint.
  4. Start PurpleRelay with the volume. 
     docker run -it -v relayvol:/app --name myrelay nathanls/purplerelay
  5. Finch is started in the background on the container as a screen session named finch. You will need to exec into the container to initially sign into the chat accounts with Finch from another terminal session. If a volume is mounted at /app on the container the Finch config will persist across restarts. You can also manually edit files within the Pidgin/Finch config directory which would be located at /app/.purple on the container and volume. 
     docker exec -it myrelay screen -r finch

    Where to Store Data

    Persist data through mounting named volumes to the /app directory within the container.

Docker Stack and Compose

Example stack.yml for PurpleRelay:

version: '3.7'
services:
  purple:
    image: nathanls/purplerelay:stable
    deploy:
      restart_policy:
        condition: any
    volumes:
      - relayvol:/app
    networks:
      - purple-network

volumes:
  relayvol:

networks:
  purple-network:
    driver: overlay

Running from source

Requirements

Installing dependencies and running

This section outlines the process for manually installing dependencies and running the application on Fedora if you choose not to utilize the Docker image of PurpleRelay.

Note: Package names and commands may differ between Linux distros.

  1. Install Python3 
    dnf install -y python38
  2. Install the PyGObject dependencies. See PyGObject install guide 
     dnf install -y gcc gobject-introspection-devel cairo-devel pkg-config python3-devel gtk3
  3. Clone and make a virtualenv 
     mkdir ~/relay
 cd ~/relay
 git clone https://github.com/Nathan-LS/PurpleRelay.git
 cd PurpleRelay
 python3 -m venv venv
 source venv/bin/activate
  4. Install requirements 
     pip3 install -r requirements.txt
  5. Rename routes-example.json to routes.json and add in your channel message routing. See Relay Configuration for information on configuration definitions. 
     mv routes-example.json routes.json
 nano routes.json

  6. Make a Discord application/bot and copy the token to config->token in the routes.json file. See the relay-configuration on this document for config reference.

  7. Ensure Pidgin or Finch is running and start the bot. 
     ./venv/bin/python3 ./PurpleRelay