dockerbot

README

dockerbot

dockerbot is a Discord & Slack bot for running interactive, command-line based Docker containers from a chat. It comes with a few container scripts by default (Ubuntu, Debian, Alpine, Arch Linux, Amazon Linux, CentOS & Fedora), but you can easily make or bring your own.

How it works

dockerbot uses tmux and the tmux capture-pane command to run most of the show.

Usage

After installing dockerbot, you may use it by tagging @dockerbot in Discord or Slack. For the most part it should be pretty self-explanatory:

To start a session with the default settings, simply say @dockerbot ubuntu to start a Ubuntu container. There are a few advanced arguments you can use when starting a session.

Session commands

When a session is started, you can get a list of available commands by typing !help (or !h). To exit a session at any point in time, type !exit (or !q).

Recording sessions

Sessions can be recorded using asciinema, and can even be automatically uploaded to either asciinema.org or your private asciinema-server (see install instructions).

After a session exits, the recording is then attached to chat as a ZIP file and optionally as a link to the asciinema server. This behavior can be controlled by the default-record and upload-recording option in the config.yml file, as well as the record/norecord option when starting a session.

Web terminal

Entering commands via Discord or Slack can be quite cumbersome, so dockerbot provides a web-based terminal (powered by ttyd). If enabled, a unique link is created for each session, which provides a read-only or writable web terminal.

This behavior can be controlled by the default-web option in the config.yml file, as well as the web/noweb option when starting a session. While a session is running, it can be toggled using the !web command.

Terminal sharing

You can share your local terminal window in Discord or Slack using the share feature. It's quite cool, although it's really got nothing to do with running containers 🤷. It also has to be specifically configured in the config.yml file using the share-host option, since it needs direct communication between the client and dockerbot.

Control mode

You can specify if you want the session to be started in the main channel (channel), in a thread (thread), or in split mode (split) using both channel and thread. Split mode is the default because it is the cleanest to use: it'll use a thread for command input and the main channel to display the terminal.

Terminal size

You can set the terminal window size when you start a session by using the keywords tiny (60x15), small (80x24), medium (100x30), and large (120x38). The default is small. You may also resize the terminal while the session is running using the !resize command.

Window mode

When starting a session, you can choose whether to trim empty space from the terminal session (trim), or whether to show the entire terminal window as it would appear in a terminal emulator (full). The default is full, as trim mode can get awkward when the terminal is expanded and the collapsed again.

Installation

Please check out the releases page for binaries and deb/rpm packages.

Requirements:

• A modern-ish Linux, preferably Ubuntu 22.04, since that's what I develop on -- though it also runs on other distros.
• tmux >= 2.6 is required, which is part of Ubuntu 18.04 (but surprisingly not part of Amazon Linux!)
• docker for almost all scripts dockerbot ships with
• asciinema if you'd like to record sessions
• ttyd if you'd like to use the web terminal feature

Creating a dockerbot Discord app:

1. Create a Discord app
2. In the "Bot" section under "Authorization Flow", untoggle "Public Bot".
3. Under "Privileged Gateway Intents" in the "Bot" section, toggle "MESSAGE CONTENT INTENT".
4. In the "OAuth2" section, click "Add Redirect" and add a URL (even https://google.com is fine). Save your changes.
5. Under the "OAuth2" section, navigate to "URL Generator". Select the following scopes: "bot" and "messages.read", then select your redirect URL you added in step 3.
6. Select the following permissions: "Read Messages/View Channels", "Send Messages", "Create Public Threads", "Create Private Threads", "Send Messages in Threads", "Manage Messages" and "Manage Threads". Save your changes.
7. Copy the OAuth2 URL and navigate to it in the browser and authorize the app.
8. In the "Bot" section, click "Reset Token", follow the prompts and then copy the displayed token.

Creating a dockerbot Slack app:
dockerbot requires a Slack "Classic App (bot)", because of its use of the real time messaging (RTM) API. To create a classic app and acquire a Slack bot token, follow these steps:

1. Create a classic Slack app
2. In the "App Home" section, add a "Legacy bot user"
3. In the "OAuth & Permissions" section, click "Install to Workspace" (this may require workspace admin approval)
4. Copy the "Bot User OAuth Token" starting with "xoxb-..."

Installing dockerbot:

1. Make sure tmux and probably also docker are installed. Then install dockerbot using any of the methods below.
2. Then edit /etc/dockerbot/config.yml to add Slack or Discord bot token. dockerbot will figure out which one is which based on the format.
3. Review the scripts in /etc/dockerbot/script.d, and make sure that you have Docker installed if you'd like to use them.
4. If you're running dockerbot as non-root user (such as when you install the deb/rpm), be sure to add the dockerbot user to the docker group: sudo usermod -G docker -a dockerbot.
5. Then just run it with dockerbot (or systemctl start dockerbot when using the deb/rpm).

Binaries and packages

Debian/Ubuntu (from a repository):

curl -sSL https://archive.grnt.dev/apt/pubkey.txt | sudo apt-key add -
sudo apt install apt-transport-https
sudo sh -c "echo 'deb [arch=amd64] https://archive.grnt.dev/apt debian main' > /etc/apt/sources.list.d/archive.grnt.dev.list"  
sudo apt update
sudo apt install dockerbot asciinema

Debian/Ubuntu (manual install):

sudo apt install tmux
wget https://github.com/runbgp/dockerbot/releases/download/v1.0.0/dockerbot_1.0.0_amd64.deb
dpkg -i dockerbot_1.0.0_amd64.deb

Fedora/RHEL/CentOS:

# Make sure that "tmux" is installed
rpm -ivh https://github.com/runbgp/dockerbot/releases/download/v1.0.0/dockerbot_1.0.0_amd64.rpm

Docker:
You can configure the Docker image by mounting a config directory (containing config.yml) to /etc/dockerbot. To be able to use most of the pre-packaged script.d containers (to be mounted to /etc/dockerbot/script.d), you'll need to give the dockerbot image access to the Docker socket file. This allows the container to spin up other containers on the host. This is a security risk and considered bad practice, but it's the only way.

# Config and scripts live on the host
wget https://github.com/runbgp/dockerbot/archive/refs/tags/v1.0.0.tar.gz
tar zxvf v1.0.0.tar.gz
sudo mkdir /etc/dockerbot
sudo cp -a dockerbot-1.0.0/config/{script.d,config.yml} /etc/dockerbot
vi /etc/dockerbot/config.yml
  # Configure at least "bot-token"
  # To support web terminal, set "web-host" (e.g. to localhost:31001)
  # To support sharing, set "share-host" (e.g. to localhost:31002)
  
# Then you can start the dockerbot docker image (assuming web-host listening
# at 31001 and share-host at 31002)
docker run --rm -it \
  -v /etc/dockerbot:/etc/dockerbot \
  -v ~/.asciinema:/root/.config/asciinema \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 31001:31001 \
  -p 31002:31002 \
  runbgp/dockerbot

Please note that if you'd like to associate the asciinema videos to an account, you need to set up and map the config directory properly. For me, that worked by installing it on the host, running asciinema rec once and then associating the install-id located in ~/.asciinema/install-id. Inside the docker image, asciinema expects the config directory to be in ~/.config/asciinema.

Go:

# Be sure "tmux" is installed
go get -u github.com/runbgp/dockerbot

Manual install (any x86_64-based Linux):

# Make sure that "tmux" is installed
wget https://github.com/runbgp/dockerbot/releases/download/v1.0.0/dockerbot_1.0.0_linux_x86_64.tar.gz
sudo tar -C /usr/bin -zxf dockerbot_1.6.4_linux_x86_64.tar.gz dockerbot

Building

Building dockerbot is simple. Here's how you do it:

make build-simple
# Builds to dist/dockerbot_linux_amd64/dockerbot

To build releases, I use GoReleaser. If you have that installed, you can run make build or make build-snapshot.

Contributing

I welcome any and all contributions. Just create a PR or an open an issue.

License

Made with ❤️ by Philipp C. Heckel and maintained by runbgp, distributed under the Apache License 2.0.

Third party tools/libraries:

• tmux (ISC) is used to run most of the show
• docker is used to run containers
• asciinema (GPLv3) is used to record sessions
• ttyd (MIT) is used to run the web terminal
• github.com/urfave/cli/v2 (MIT) is used to drive the CLI
• discord-go (BSD-3) is used for the Discord communication
• slack-go (BSD-2) is used for the Slack communication
• gliderlabs/ssh (BSD-3) is used for remote port forwarding for terminal sharing
• stretchr/testify (MIT) is used in most of the tests

Code and posts that helped:

• tmux sharing across hosts, thanks to QuAzI

Documentation

Overview

dockerbot is a Discord & Slack bot for running interactive, command-line based Docker containers.