Signal CLI Device Linking with Persistence

[jmealo]

The problem

Adapting the docker instructions in the README to docker compose can lead to a persistence issue #745 .

I'm thinking this could be a documentation update?

Solution:

After extensive debugging, here's the complete solution for persistent Signal device linking:

Root Cause

When using docker exec signal-cli-rest-api signal-cli link ... without specifying the config directory, the registration data is written to /root/.local/share/signal-cli/ (ephemeral container storage) instead of the mounted
volume at /home/.local/share/signal-cli/.

Solution

1. Use a bind mount instead of a named volume:

services:
  signal-cli-rest-api:
    volumes:
      - ./signal-cli-config:/home/.local/share/signal-cli  # Bind mount
    environment:
      - MODE=native
      - SIGNAL_CLI_UID=1000
      - SIGNAL_CLI_GID=1000

2. Link device with correct config path:

# Generate link URI (with --config flag to write to persistent location)
docker exec signal-cli-rest-api signal-cli \
  --config /home/.local/share/signal-cli \
  link -n "device-name"

# Copy the sgnl://linkdevice?uuid=... URI

# On your primary device (local machine):
signal-cli -a +YOUR_NUMBER addDevice --uri "sgnl://linkdevice?..."

# Fix permissions for signal-api user (UID 1000):
sudo chown -R 1000:1000 ./signal-cli-config/

# Restart container to load registration:
docker compose restart signal-cli-rest-api

3. Verification

After restart, verify persistence:
docker compose restart signal-cli-rest-api
curl "http://localhost:8080/v1/accounts"
# Should return: ["+YOUR_NUMBER"]

The registration data will now persist.

### Are you using the latest released version?

- [x] Yes

### Have you read the troubleshooting page?

- [x] Yes

### What type of installation are you running?

signal-cli-rest-api Docker Container

### In which mode are you using the docker container?

Normal Mode

### What's the architecture of your host system?

x86-64

### Additional information

_No response_