prerequisites

You need a (private) IRC channel somewhere. I personally run my own IRC server using Oragono. It’s on the same server as my IRC bouncer, so I do not have to expose it to the Internet (side-note: if someone has documentation about how to set up a secured, private IRC server with strict user authentication against some backend, I’d love to hear about it). You could also use a private channel on a public network though.

You also need a server to run TikTokBot itself, which requires ruby (here, the same VPS running Debian 8 that runs all my stuff).

primer on running Ruby programs

(I’m not a Ruby dev, corrections welcome)
Ruby dependencies are organized in "Gems". A project’s Gemfile lists all dependencies of the project. A Gemfile.lock is generated to freeze exact versions of the dependencies. Bundler is a tool to create an isolated environment for a project, and then to run applications in this environment (instead of installing dependencies globally, they end up in a .vendor subdirectory)

install TikTokBot

First, install ruby and bundler:

$ apt install ruby bundler

Create a directory for TikTokBot, and download it there. I cloned the git repo, but of course you can also download the zip file from Github and upload it’s contents.

# git clone https://github.com/aaronpk/TikTokBot.git

check your ruby version

# ruby -v

if it is below 2.2.2, the dependency version snapshot in the current Gemfile.lock doesn’t work. As a workaround, I just deleted it, and let the installation pick it’s own versions, and it works out OK for now.

install dependencies:

# bundle install

configure TikTokBot

TikTokBot has 3 configuration files.
In config.yml a server needs to be defined, and to bot is instructed to join a channel (e.g. #webmentions) – look at the example file for reference. Similarly, in token.yml at least a global token has to be created – all other lines can be deleted. We don’t need any hooks (=webhooks sent when specific things are said in IRC), so hooks.yml is filled with

hooks: []

start TikTokBot

as described in the README, run

# bundle exec ruby tiktok.rb localirc

(replace localirc with the name of your server definition)
Now the bot should connect to IRC and appear in the channel.

test sending

Now we’ll send the bot a command to send a message to the channel. This is done by sending a form-encoded POST request to the /messag endpoint of it’s API, e.g. using curl:

# curl -H "Authorization: Bearer TOKEN" -X POST -F 'channel=#webmentions' -F 'content=HELLO WORLD!' http://localhost:9000/message

(obviously, fill in your actual token, the channel and the API location)

persistent start using systemd

I’ve written a systemd unit file for TikTokBot, which runs it as it’s own user and group (which have to be created before):

[Unit]
Description=Tiktokbot for local IRC

[Service]
ExecStart=/usr/local/bin/bundle exec ruby tiktok.rb localirc
WorkingDirectory=/srv/bots/tiktokbot
User=tiktokbot
Group=tiktokbot

[Install]
WantedBy=multi-user.target

Place it in /etc/systemd/system/ as e.g. tiktok_local.service and systemctl enable and systemctl start it.

integrate with the rest of your site

Now, you can start sending form-encoded POST requests just as above to TikTokBot and it’ll report events in IRC.

note on restarts

During testing it has occasionally happened to me that the API portion of TikTokBot didn’t shut down cleanly, which meant that starting TikTokBot again failed with an error like

* Listening on tcp://127.0.0.1:9030
== Someone is already performing on port 9030!

In this case, you have to manually kill the left-over puma processes. If you find a solution to this problem, please contribute it at this GitHub issue