Remote Watcher

A remote watcher runs on your NAS and sends real-time file change notifications to Pellicle over your local network. This means new photos appear in your library instantly, without waiting for a periodic rescan.

Requirements

• A NAS or server with Docker support (Synology, QNAP, Unraid, etc.)
• The photo folder mounted or accessible on both the NAS and your Mac
• Both devices on the same local network

1. Generate a Secure Token

The watcher uses a shared token to authenticate connections. Generate one by running this in Terminal:

ruby -rsecurerandom -e 'puts SecureRandom.hex(32)'

Copy the output — you'll use it in both the watcher config and in Pellicle's settings.

2. Create the Configuration File

Create a file called config.yml on your NAS:

port: 7849
token: "paste-your-generated-token-here"

watch_roots:
  - path: /data/Photography
    name: Photography

mdns:
  enabled: true
  instance_name: "NAS Photography"

tls:
  enabled: true
  san:
    - "192.168.1.100"

Configuration options

• port — The port the watcher listens on (default: 7849).
• token — The shared secret used to authenticate connections. Must match the token configured in Pellicle.
• watch_roots — One or more directories to watch for changes. path is the path inside the container, and name is a human-readable label.
• mdns — When enabled, the watcher advertises itself on the local network so Pellicle can discover it automatically.
• tls — TLS encryption settings (see below). Enabled by default.

TLS encryption

All connections between Pellicle and the watcher are encrypted with TLS. This is enabled by default — no extra configuration is needed in most cases.

On first start, the watcher automatically generates a self-signed certificate and saves it to /etc/pellicle-watcher/tls/ inside the container. Mount this directory as a volume so the certificate persists across container restarts.

Pellicle uses Trust On First Use (TOFU) to verify the watcher's identity. The first time Pellicle connects, it accepts the certificate and saves its SHA-256 fingerprint. All subsequent connections must present the same certificate, protecting against man-in-the-middle attacks.

The tls section supports these options:

• enabled — Enable or disable TLS (default: true). Should only be disabled for debugging.
• cert_dir — Directory for the certificate and key files (default: /etc/pellicle-watcher/tls).
• san — Extra Subject Alternative Names to include in the generated certificate. Add your NAS's IP address or hostname here if you connect by IP rather than mDNS.

3. Deploy the Container

Follow the guide for your NAS:

• Synology NAS Setup — using Container Manager (DSM 7.2+)
• QNAP NAS Setup — using Container Station
• SSH / Command Line Setup — for Unraid, generic Linux, or any system with SSH access

4. Configure Pellicle

1. Open Pellicle > Settings (or press ⌘,).
2. Go to the Remote Watchers tab.
3. If mDNS discovery is working, your watcher should appear automatically. Click it to add it.
4. Otherwise, click Add Watcher and enter the URL (e.g. wss://192.168.1.100:7849) and the token you generated.
5. Assign the watcher to an indexed folder by selecting the folder in the sidebar, then choosing the watcher and the matching watch root in the folder settings.

Once connected, you'll see an antenna icon next to the folder in the sidebar. A green antenna means the connection is active. The icon pulses when file events are received.

Troubleshooting

Watcher not discovered automatically

• Ensure mdns.enabled is true in config.yml.
• Verify network_mode: host is set in docker-compose.yml. Without it, mDNS packets can't reach the local network.
• Some NAS models restrict mDNS from containers. Try adding the watcher manually using its IP address instead.

Connection fails or keeps reconnecting

• Check that the token in Pellicle matches the one in config.yml exactly.
• Ensure port 7849 (or your chosen port) is not blocked by a firewall.
• Check the watcher logs: docker compose logs pellicle-watcher.

Certificate fingerprint mismatch

If the watcher's certificate changes (e.g. the TLS volume was deleted, or the container was recreated without a persistent volume), Pellicle will reject the connection because the fingerprint no longer matches. To fix this:

1. In Settings > Remote Watchers, remove the affected watcher.
2. Re-add it. Pellicle will trust the new certificate on first connection.

Increasing inotify watches

For very large photo libraries, you may need to increase the inotify watch limit. If your NAS supports container sysctls, add this to docker-compose.yml:

    sysctls:
      - fs.inotify.max_user_watches=524288

Otherwise, set it on the host system:

echo 524288 | sudo tee /proc/sys/fs/inotify/max_user_watches