William Vaughn

Running Bitlbee & Signald with Docker

Bitlbee is an IRC server which bridges to other common chat applications. I use it to text my friends on Signal from an Emacs ERC buffer. It’s possible to run bitlbee as a Docker container and systemd service on your personal Linux system, that’s what this blog will show you how to do.


In order for Bitlbee to work with Signal, you need some libraries, signald and libpurple-signald. The libpurple library is a common requirement for many bitlbee bridges, and fortunately there is already a suitable docker container with bitlbee and libpurple pre-installed, ezkrg/bitlbee-libpurple. However, it does not have signald installed in it. We will need to run another container, finn/signald, and give the bitlbee container access to it via a shared volume. Once the containers are set and available, we’ll use systemd to ensure they start on boot.

  1. Setup Storage & Cross Communication Volumes
  2. Run the Containers
  3. Login & Verify Device with Signal
  4. Create a Systemd User Unit

Setup Storage & Cross Communication Volumes

mkdir -p ~/.cache/docker-bitlbee/bitlbee
mkdir -p ~/.cache/docker-bitlbee/signald
chmod 777 ~/.cache/docker-bitlbee/bitlbee
chmod 777 ~/.cache/docker-bitlbee/signald

Run the Containers:

docker run \
    --name docker-signald.service \
    --detach \
    --restart=unless-stopped \
    -v ~/.cache/docker-bitlbee/signald/run:/signald \
docker run \
    -p 6667:6667 \
    --name docker-bitlbee.service \
    --detach --restart=unless-stopped \
    -v ~/.cache/docker-bitlbee/bitlbee:/var/lib/bitlbee \
    -v ~/.cache/docker-bitlbee/signald/run:/var/run/signald \

Login & Verify Device with Signal

More official instructions are available at libpurple-signald HOWTO.md.

Connect your IRC client to the bitlbee container. To do that with ERC in Emacs I can evaluate the following elisp.

(erc :server "localhost" :port 6667 :nick "willvaughn")

Once connected, register the user.

register <password>

Then add the Signal bridge from the &root channel.

account add hehoe-signald +12223334444
account hehoe-signald set tag signal
account signal set auto-join-group-chats true
account signal set nick_format %full_name-sig
account signal on

This is going to fail and print out a qrencode command. The docker container doesn’t have qrencode installed it. Until that is fixed, you can work around it by installing qrencode on your system and running the failed command. The result will be a QR code image that you can scan in your signal phone app to verify the new signald device.

For myself on Arch Linux, this is what I did:

sudo pacman -S qrencode
qrencode -s 6 -o /tmp/signald_link_purple_qrcode.png 'tsdevice:/?uuid=yadayada'
xdg-open /tmp/signald_link_purple_qrcode.png

Once you scan the QR code witht he Signal app on your phone, you should receive a logged in message in your IRC client.

Finish configuration and enablement of the &signal account/channel. See bitlbee docs on Managing contact lists.

These are the channel settings I ran.

channel &signal set account signal
channel &signal set fill_by account
channel &signal set auto_join true
rename _12223334444 myname-sig

Save it (ends up in our shared docker volume so we don’t have to do this everytime we log in).


Create a Systemd User Unit

For more on how systemd works see Systemd/User - How It Works.

Make a signald service at .config/systemd/user/docker-signald.service

Description=A signald container service

ExecStart=/usr/bin/docker start -a docker-signald.service
ExecStop=/usr/bin/docker stop docker-signald.service


Make the bitlbee service at ~/.config/systemd/user/docker-bitlbee.service

Description=A Bitlbee IRC bridge container

ExecStart=/usr/bin/docker start -a docker-bitlbee.service
ExecStop=/usr/bin/docker stop docker-bitlbee.service


Inform Systemd about these unit changes.

systemctl --user daemon-reload

Start the IRC service.

systemctl --user  enable docker-signald.service
systemctl --user  enable docker-signald.service


That should do it. I hope this has helped you run bitlbee on your system.