matrix-docker-ansible-deploy/docs/configuring-playbook-fluffygate.md

Setting up Fluffygate (optional)

The playbook can install and configure Fluffygate, a simple Push Gateway for Fluffychat.

See the project's documentation to learn what it does and why it might be useful to you.

Note: most people don't need to install their own gateway. This optional playbook component is only useful to people who develop/build their own Matrix client applications themselves, as you'll need access to your own Firebase/FCM and APNS credentials.

Adjusting the playbook configuration

To enable Fluffygate, add the following configuration to your inventory/host_vars/matrix.example.com/vars.yml file:

matrix_fluffygate_enabled: true

# Basic app information
matrix_fluffygate_app_name: "Your App Name"
matrix_fluffygate_app_website: "https://example.com"

# Firebase/FCM configuration (for Android / IOS)
matrix_fluffygate_firebase_project: "your-firebase-project-id"
matrix_fluffygate_firebase_key: |
  {
    # Your Firebase service account key JSON content
  }  

# Notification settings
matrix_fluffygate_notification_title: "{count} new messages"
matrix_fluffygate_notification_body: "{body}"

# Android specific notification options
matrix_fluffygate_android_notification_options:
  priority: high
  notification:
    sound: "default"
    icon: "notifications_icon"
    tag: "default_notification"

# APNS specific notification options (for iOS)
matrix_fluffygate_apns_notification_options:
  headers:
    apns-priority: "10"
  payload:
    aps:
      sound: "default"
      badge: "{count}"
      mutable-content: 1

For a complete list of available configuration options, see the defaults/main.yml file in the role.

Required Configuration

The following settings are required and must be defined:

• matrix_fluffygate_hostname
• matrix_fluffygate_path_prefix
• matrix_fluffygate_container_network
• matrix_fluffygate_app_name
• matrix_fluffygate_app_website

Adjusting the Fluffygate URL

By default, this playbook installs Fluffygate at the root path (/) of the configured hostname. You can customize both the hostname and path prefix using these variables:

# Configure the hostname where Fluffygate will be served
matrix_fluffygate_hostname: "push.example.com"

# Configure a custom path prefix (must either be '/' or not end with a slash)
matrix_fluffygate_path_prefix: /push

Traefik Integration

Fluffygate includes built-in support for Traefik as a reverse proxy. The following settings control this integration:

# Enable/disable Traefik labels
matrix_fluffygate_container_labels_traefik_enabled: true

# Configure the Traefik network
matrix_fluffygate_container_labels_traefik_docker_network: "{{ matrix_fluffygate_container_network }}"

# Additional Traefik configuration
matrix_fluffygate_container_labels_traefik_rule: "Host(`{{ matrix_fluffygate_container_labels_traefik_hostname }}`)"
matrix_fluffygate_container_labels_traefik_priority: 0
matrix_fluffygate_container_labels_traefik_entrypoints: web-secure

Adjusting DNS records

You will need to configure your DNS records to point the Fluffygate hostname to your server. This typically involves creating either:

• an A record pointing to your server's IPv4 address
• a CNAME record pointing to your server's hostname

Installing

After configuring the playbook and adjusting your DNS records, run the installation command:

ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

To install only Fluffygate, you can use:

ansible-playbook -i inventory/hosts setup.yml --tags=setup-fluffygate,start

Usage

To make use of your Fluffygate installation:

1. Configure your Matrix client application to use your Fluffygate URL as the push gateway
2. Ensure your app uses the same Firebase/FCM credentials for Android notifications
3. Ensure your app uses the same APNS certificates/credentials for iOS notifications
4. Configure the notification templates and options as needed through the playbook variables

Debugging

If you need to troubleshoot issues:

1. Enable debug logs by setting:

matrix_fluffygate_debug_logs: true

2. Check the container logs:

docker logs matrix-fluffygate

Uninstalling

To remove Fluffygate, first disable it in your inventory/host_vars/matrix.example.com/vars.yml:

matrix_fluffygate_enabled: false

Then run the playbook:

ansible-playbook -i inventory/hosts setup.yml --tags=setup-fluffygate,start

This will stop the service and remove all associated files.