The mautrix-signal matrix application recently announced an update to v0.5.0, which involves a significant change to how it works. Previously (e.g. in v0.4.3), the application depended on a running instance of signald to integrate mautrix-signal with the signal network. Starting with v0.5.0, this dependency is no longer there, as the application can now integrate directly.

Unfortunately, the upgrade documentation is not really clear. All we get is:

The bridge doesn't use signald anymore, all users will have to re-link the bridge.

… which doesn't help me know the different experiences admins and users will have.

I'm always nervous of major upgrades like this and the potential damage I could bring to my service if I don't understand what's going to happen, so I asked on the Mautrix-Signal Bridge room what this might mean:

Hi. I'm looking at the changelog for v0.5.0 and v0.5.1 and can someone explain to me what "… all users will have to re-link the bridge" means, please? Thanks.

Unfortunately, the responses I received weren't really helpful1 (in part, I'm sure, because I wasn't explicit in my question as to what information I was looking for), so see below for an outline of my experience with the upgrade, provided in terms of the experience of the home server admin and of the matrix user who uses the bridge.

The Admin experience

I use docker for mautrix-signal. For v0.4.3 and below, this involved three containers:

the main matrix application integrated with my home server.
(version 13.7) the database for mautrix-signal
(version 0.23.2) the means to integrate with the signal network.

Prior to doing anything, I shut down all of these containers and backed up the volumes (i.e. the data and config files) to make sure I had something to fall back to should anything go wrong.

I then restarted the postgres container to make the database available for the upgrade of mautrix-signal. The upgrade documentation stated that the "… bridge doesn't use signald anymore …", so I didn't restart the signald container.

I then re-created the mautrix-signal container with the following commands, and then waited a minute or so for the database to be upgraded2:

docker rm mautrix-signal
docker run -d \
       -v ${INST_DIR}/mautrix-signal/bridge:/data \
       -v ${INST_DIR}/signald-mautrix-signal/signald:/signald \
       --name mautrix-signal \
       --network matrix-synapse \
       --ip <IP-ADDRESS> \

The docker run command is the same as what I used before the upgrade, except for the version number of the docker image. I decided to make only that change, but I will remove the -v specification for the /signald volume once I'm happy it's working well.

If there were more users than I on the home server that uses the bridge, I would alert them that they need to "… re-link the bridge …" with the following instructions.

The User experience

The user would go to the Signal bridge bot room that they created when they initially linked their Signal account to their matrix account.

I would advise users to issue the help command to see the new commands and options that are available following the upgrade. Then I would advise them to issue the ping command to see their login status. They're almost certainly going to be told …

You were logged in at some point, but are not anymore

The user would then issue the command login. The bot will respond with a QR code and a link.

The user will then go to their Signal app (on their mobile device, I guess) and, using Settings, go to add a new device. The user can then either scan the QR code or enter the link provided by the bot. Signal will ask to confirm the device and the user will tap the tick-mark to do so.

The user's matrix account is now re-linked to their signal account through the upgraded bridge.

The first time I attempted this, it timed out. The bot removed the messages with the QR code and the URL and issued an error message detailing the timeout.

On the second attempt, I did it quickly enough. Once the bridge noticed that the login succeeded, it removed the second set of QR code and URL messeges and issued a "Successfully logged in as …" message to the room.

I don't use double-puppeting (yet – another thing I need to properly understand before I use it, for fear that I might break something), so I didn't issue the login-matrix command; I can't describe that experience.



… or respectful – I often find that room to be quite unwelcoming


I don't use docker compose, and you may be curious about some of the configurations here. You're welcome to '@' me, but I'm unlikely to respond well to a tone that suggests I'm doing something wrong.

You can comment on this post below, or on the matrix room here. If you want, you can "Log in" using your [matrix] ID.

All comments are subject to this site's comment policy.