Table of contents
Requirements
- Docker
- A Matrix homeserver that supports application services (e.g. Synapse)
Setup
Docker images are hosted on dock.mau.dev
- Create a directory for the bridge and cd into it:
mkdir mautrix-whatsapp && cd mautrix-whatsapp.
N.B. The docker image willchownits/datadirectory to UID 1337. The commands below mount the working directory as/data, so make sure you always run them in the correct directory. - Pull the docker image with
docker pull dock.mau.dev/tulir/mautrix-whatsapp:latest. - Run the container for the first time, so it can create a config file for you:
docker run --rm -v `pwd`:/data:z dock.mau.dev/tulir/mautrix-whatsapp:latest - Update the config to your liking. Don't forget to change the
addressanddomainto match those of your server. Don't change the database URI if using SQLite. - Generate the appservice registration by running the container again, same command as above.
- Add the path to the registration file (
registration.yamlby default) to your Synapse'shomeserver.yamlunder theapp_service_config_filessection:app_service_config_files: ["/path/to/your/mautrix-whatsapp/registration.yaml"] - Restart Synapse to apply changes.
- Run the bridge:
N.B. If using postgres database hosted at localhost/127.0.0.1 (outside the container), then usedocker run --restart unless-stopped -p 29318:29318 -v `pwd`:/data:z dock.mau.dev/tulir/mautrix-whatsapp:latest--network=hostto avoid errors likedial tcp 127.0.0.1:5432: connect: connection refused
Upgrading
- Pull the new version (setup step 1)
- Start the new version (setup step 7)
Docker compose
If you already run synapse using docker-compose:
- Edit the
docker-compose.ymland add themautrix-whatsappsection as stated below.
If not, consider doing it. It can simplify things a lot. Otherwise:
- create a directory as in step #0 and create
docker-compose.ymlthat contains something like this:
version: "3.7"
services:
mautrix-whatsapp:
container_name: mautrix-whatsapp
image: dock.mau.dev/tulir/mautrix-whatsapp:latest
restart: unless-stopped
environment:
- UID=XXXX # (optional) User id of your docker user. Make sure to use the same one for your server (synapse).
- GID=XXXX # (optional) Group id of your docker user.
volumes:
- ./mautrix-whatsapp/:/data # Use a sub directory if you plan to run another bridge.
- Start the bridge once with
docker-compose up mautrix-whatsappto generate the config file. - Edit the
config.yamlwith the correctaddressanddomain. Proposed changes:
homeserver:
address: https://<your server domain>
domain: <your server domain>
appservice:
address: http://mautrix-whatsapp:29318 # depends on the name you chose in the `docker-compose.yml`. Only works if synapse is defined in the same docker-compose.yml.
hostname: mautrix-whatsapp
- Run
docker-compose up -d mautrix-whatsappto start the bridge and to generate theregistration.yaml. - (Optional) If you didn't use the user and group id environment variables, fix ownership of
registration.yaml. If synapse is running as root, ignore this step. - If the mautrix-whatsapp volume is not reachable by synapse, copy
registration.yamlsomewhere into the synapse volume path. - Edit
homeserver.yamland add the path to theregistration.yamltoapp_service_config_files:
app_service_config_files:
- "/path/to/your/mautrix-whatsapp/registration.yaml"
- Restart synapse
docker-compose restart synapse
Use docker-compose up -d to start, docker-compose stop to stop.
To update, run docker-compose pull to download the new images and docker-compose up -d to recreate running containers with the updated ones.
Adding UID and GID is optional, but encouraged. Otherwise the registration.yaml might not be readable by synapse.
Note
If you have connection problems and changed something in your config.yaml, delete registration.yaml and mautrix-whatsapp.db, then restart the bridge. Those files are not recreated automatically and need to be regenerated after making changes in the config.
Wiki deprecated
mautrix-whatsapp docs are now on docs.mau.fi