MollySocket

MollySocket allows getting signal notifications via UnifiedPush. It works like a linked device, which doesn't have an encryption key, connected to the Signal server. Everytime it receives an encrypted event, it notifies your mobile via UnifiedPush.

Overview

---
title: Message flow
---
graph TD
    
    MS[fa:fa-tablets MollySocket]
    S[fa:fa-comment Signal Server]
    P[fa:fa-server Push server]
    subgraph "fa:fa-mobile Android"
        D[fa:fa-tower-broadcast Distributor App]
        MA[fa:fa-tablets Molly Android]
    end
    MS -- #8203;1. Persistent connection --> S
    MS -- #8203;2. 'Notifications present' --> P
    P -- #8203;3. 'Notifications present for Molly' --> D
    D -- #8203;4. 'Check Signal servers' --> MA
    MA -- #8203;5. 'Got messages?' --> S
    S -- #8203;6. Messages --> MA

Setup

You can install MollySocket via:
1. Docker/Podman: docker pull ghcr.io/mollyim/mollysocket:latest
2. Crates.io: cargo install mollysocket (see INSTALL.md for the setup)
3. Direct download: https://github.com/mollyim/mollysocket/releases (see INSTALL.md for the setup)
A distributor app (easiest is ntfy)
Go to the Settings > Notifications, change the delivery method to UnifiedPush and scan the QR code shown on your MollySocket homepage

You can optionally install your own push server like ntfy or NextPush. For beginners, you can use a free service like ntfy.sh (do consider donating if you have the means).

Web Server

MollySocket exposes a web server so that Molly can send the information it needs to operate. You must configure TLS with a reverse proxy in front of MollySocket. Molly can only connect to the server over HTTPS.

It is possible to use MollySocket without the web server, but you will have to manually register the information MollySocket needs: see the Air Gapped mode on Android settings.

Configuration

The configuration file uses the TOML format. Below is an overview of configuration options. You can configure each parameter using either the conf file, the environment variable or the cli option (if available).

| Parameter (conf. file) | Environment variable | Cli Option | Description | Default | Examples | |------------------------|----------------------------|-------------|---------------------------------------------------|----------------------|---------------------------------------------------------| | | RUST_LOG * | -v/-vv/-vvv | Verbosity | error | RUST_LOG=info, RUST_LOG=debug | | | MOLLY_CONF | -c * | Path to the configuration file, optional | | /etc/mollysocket.conf | | host | MOLLY_HOST * | | Listening address of the web server | 127.0.0.1 | 0.0.0.0 | | port | MOLLY_PORT * | | Listening port of the web server | 8020 | 8080 | | webserver | MOLLY_WEBSERVER * | | Wether to start the web server | true | false | | allowed_endpoints | MOLLY_ALLOWED_ENDPOINTS * | | List of UnifiedPush servers | ["*"] | ["*"],["https://yourdomain.tld","https://ntfy.sh"] | | allowed_uuids | MOLLY_ALLOWED_UUIDS * | | UUIDs of signal accounts that may use this server | ["*"] | ["*"], ["abcdef-12345-tuxyz-67890"] | | db | MOLLY_DB * | | Path to the DB | db.sqlite | "/data/ms.sqlite" | | vapid_privkey | MOLLY_VAPID_PRIVKEY * | | VAPID key, see VAPID key | None | "DSqYuWchrB6yIMYJtidvqANeRQic4uWy34afzZRsZnI" | | vapid_key_file | MOLLY_VAPID_KEY_FILE * | | File with VAPID key, see VAPID key | None | "/etc/ms_vapid_key" |

* Takes the precedence

VAPID key

VAPID key is used to authorize mollysocket server to send requests to your push server, if it supports it.

To generate a new key, you can run this command mollysocket vapid gen. Or using docker, docker compose run mollysocket vapid gen.

This value can be passed to mollysocket via a file, location given with vapid_key_file parameter, or directly in the vapid_privkey parameter. The key file takes the precedence.

With docker-compose

The easiest way to pass the VAPID key when using docker compose is to pass it with the MOLLY_VAPID_PRIVKEY environment variable. See docker-compose.yml.

With a systemd service

If you use a systemd service for MollySocket, installation steps are listed in <./INSTALL.md>

Alternatively, you can store the VAPID key in cleartext in the systemd unit file:

[Service]
Environment=MOLLY_VAPID_PRIVKEY=DSqYuWchrB6yIMYJtidvqANeRQic4uWy34afzZRsZnI

`allowed_endpoints`

These are the UnifiedPush endpoints that MollySocket may use to push notifications with.

⚠️ If you self-host your push server, add your push server to the allowed_endpoints. ⚠️

That's because, for security reasons, endpoints on your local network must be allowed explicitly. You just have to set the scheme (https), the domain and the port if required. For instance allowed_endpoints=['https://push.mydomain.tld']

`allowed_uuids`

You can allow registration for all accounts by setting allowed_uuids to ['*']. Else set your account ids in the array: ['account_id1','account_id2'].

The account IDs are showing in the Molly application under Settings > Notifications > UnifiedPush. You need to activate UnifiedPush first before your account ID is shown.

Troubleshoot

Where is the MollySocket QR code?

First of all, setting up VAPID is a requirement to get this QR code, if you haven't please refer to section above.

MollySocket is primarily designed to be run behind a reverse proxy. If this is the case, open your MollySocket URL in your browser and scan the QR code, or take a screenshot.

If you don't use MollySocket behind a reverse proxy, you wish to use it in air-gapped mode, then:

If you can use port-forwarding through SSH to your server, then run the following command: ssh -L 8020:localhost:8020 your_server, then open http://localhost:8020 on your machine. You can ignore alerts if there are any. Then click on airgapped mode.
If you can't use port-forwarding, change webserver to false in your config file, or via the environment variable MOLLY_WEBSERVER=false and restart your service:

# systemctl restart mollysocket
# journalctl -u mollysocket
# # This should show a QR code

Scanning a QR code displayed on a dark theme currently doesn't work, so turn on your light theme before scanning.

How to backup VAPID key?

MollySocket is designed for self-hoster, and the idea is to renew the VAPID key if you have to reinstall MollySocket somewhere else. If you are asking for this, you are probably trying to use systemd-creds, else you'd have the VAPID private key in plain text.

If you haven't generated the VAPID key yet, just pipe the command to a temporary file: mollysocket vapid gen | tee key.tmp | systemd-creds encrypt --name=ms_vapid -p - -, key.tmp will contain the key, you can store it in a safe and remove the file.

If you have already generated the key, and want to back up this key, you can retrieve it this way: First, copy the content of SetCredentialEncrypted to a file ms_vapid. Then use systemd-creds to decrypt it. You can then store it in a safe.

# cat cipher.cred
k6iUCUh0RJCQyvL8k8q1UyAAAAABAAAADAAAABAAAAC1lFmbWAqWZ8dCCQkAAAAAgAAAA
AAAAAALACMA0AAAACAAAAAAfgAg9uNpGmj8LL2nHE0ixcycvM3XkpOCaf+9rwGscwmqRJ
cAEO24kB08FMtd/hfkZBX8PqoHd/yPTzRxJQBoBsvo9VqolKdy9Wkvih0HQnQ6NkTKEdP
HQ08+x8sv5sr+Mkv4ubp3YT1Jvv7CIPCbNhFtag1n5y9J7bTOKt2SQwBOAAgACwAAABIA
ID8H3RbsT7rIBH02CIgm/Gv1ukSXO3DMHmVQkDG0wEciABAAII6LvrmL60uEZcp5qnEkx
SuhUjsDoXrJs0rfSWX4QAx5PwfdFuxPusgE==
# systemd-creds decrypt ms_vapid
DSqYuWchrB6yIMYJtidvqANeRQic4uWy34afzZRsZnI

On MollySocket webpage, I see a alert saying the origin or the Pathname isn't correct

You are using MollySocket behind a reverse proxy and the URL received by MollySocket doesn't match the one you are using in your web browser.

You need to pass the original Host and the original URL to MollySocket with the Host and the X-Original-URL header. For instance, the Nginx config looks like this:

    # change to /molly/ if you don't expose it on the root of your domain
    location / {
        proxy_pass http://127.0.0.1:8020/;
        proxy_set_header            Host $host;
        proxy_set_header X-Original-URL $uri;
    }

On the Android app, the status states Invalid response from server

The MollySocket server can't be reached on that URL or doesn't respond correctly. Does opening the URL in your mobile browser works ? You should see a QR code. Else, try to reconfigure MollySocket, by clicking on "MollySocket server" in Molly settings.

**On the Android app, the status states _The account ID is refused by the serv

Mollysocket

Install / Use

README