TapChat is an OpenSource IRC Client for Android. It provides push notifications with the help of a Node.js server application that serves as an IRC bouncer.

While the TapChat website provides setup instructions for a Debian based system where you have sudo rights, this post is about setting the thing up as a permanent service on an unprivileged Uberspace SSH account. It might be helpful for use on similar accounts with other providers as well, however I do make use of some of uberspace’s helper scripts. But wait…

A what?

Bouncer is just IRC lingo for proxy - an IRC bouncer is just a piece of software running somewhere on a server that stays connected to your IRC networks of choice all the time.

Whenever a client (in this case, the TapChat Android app) connects to the bouncer, the latter can provide a replay of all the messages that occured since the client was last seen. In addition to that, the bouncer can react to what happens in the channels you joined while you are offline or not running the TapChat app on your phone, which is what it does to send out push notifications whenever your nick name is mentioned in a channel.

Where to run the thing

This is the kind of task where having a shell account at a reliable hoster comes in very handy. I’m a happy customer of Uberspace, they provide everything you need (and most probably a lot more) together with stellar support and a pay what you want pricing model. Hard to beat if you ask me.

So if you want to follow along and not already have an account there, give them a try.

Ok let’s do it

The next commands assume you are logged into your uberspace account.

First of all some Node.js setup. Node is already installed, we just need some personal configuration for NPM, telling it where to install stuff:

$ mkdir ~/node
$ cat > ~/.npmrc <<__EOF__
prefix = $HOME/node
umask = 077
__EOF__

$ npm install tapchat -g
$ cd ~/node/lib/node_modules/tapchat && npm install

I’m no Node.js export, so I cannot explain why the last step is necessary, but without it tapchat refused to start.

$ ~/node/bin/tapchat start

You will now be asked for a port number, username and password. The port will be the port that you will later connect to from Android / your browser. Uberspace has some guidelines for choosing port numbers, it boils down to

• only use ports between 61000 and 65535
• to have your port made accessible from the rest of the internet, just ask
• before you do that, check if the port is still unused on your machine: netstat -tulpen | grep YOUR_PORT

So pick a port number, drop them a line and continue. Take note of the SSL fingerprint the setup process writes out at the end. You can set up an SSH tunnel from your local machine for the time until they opened up the port (replace PORT with your port number of course)

ssh -L PORT:localhost:PORT username@servername.uberspace.com

Now point your browser to https://localhost:PORT. Your browser will complain about the certificate - just compare the certificate’s fingerprint with the one from earlier on and if they match, accept the certificate permanently. You should now be able to log in using the username and password you picked. There’s not much to see but what is there is pretty self explanatory. Basically this is the place where you configure any IRC networks that you wish to connect to.

Once Uberspace confirmed that your port is open you can ditch the tunnel and connect directly to https://servername.uberspace.de:PORT. Now you can also set up your Android app by pointing it to servername.uberspace.de:PORT and entering your username and password. Since all IRC connections are already configured in the bouncer web app, there’s not much more to configure here.

Make it right

Using the uberspace-provided daemontools helper scripts it is super easy to turn TapChat into a managed system service. This way it will be restarted when needed, and you will be notified if there’s anything wrong (i.e. if it keeps crashing).

The Uberspace Daemontools wiki page has been a very helpful resource here, basically it’s just copy’n’paste. First, set up daemontools for your account in case you haven’t yet, then, create a tapchat managed service:

test -d ~/service || uberspace-setup-svscan
uberspace-setup-service tapchat ~/node/bin/tapchat start -f

The -f makes tapchat stay in the foreground, which is a requirement for daemontools to be able to manage it properly.

You may now start / stop the service at will using these commands:

# bring it Up
svc -u ~/service/tapchat
# bring it Down
svc -d ~/service/tapchat

Make sure you stop any already running tapchat instance (~/node/bin/tapchat stop) before trying this.

Bonus points - custom highlight words

The major problem I had with TapChat was it’s lack of a custom higlight word list, which let me configure additional terms that, when they occur in a channel I joinded, would trigger a push notification. There’s a Github issue for this already, but for the time being, I hacked this into the TapChat server, which turned out to be really easy. It’s written in Coffee Script, so the hardest thing actually was to find out how to recompile the thing.

All you need to do is open ~/node/lib/node_modules/tapchat/src/tapchat/connections.coffee and modify the shouldHighlight method which was located on line 330 at the time of this writing. We have a convention to prefix what we call public service announcements with the string PSA at Planio so here’s what my shouldHighlight method looks like now:

shouldHighlight: (message) ->
  message && ///(#{@getNick()}|psa)///i.test(message)

As you can see, no big deal. In order to compile the changed source into proper Javascript run npm install one more time:

cd ~/node/lib/node_modules/tapchat && npm install

Don’t forget to restart the tapchat service so it picks up the changes.