synapse-docker-bridges/ADDING_BRIDGES.md

Adding New Bridges Guide

This guide explains how to integrate additional Matrix bridges into your Synapse setup. It covers the general process and provides a template for maintaining consistency with the existing bridge configurations.

Prerequisites

Before adding a new bridge, ensure you have:

• A working Synapse setup using this repository's structure.
• Basic understanding of Docker and Docker Compose.
• Familiarity with Matrix bridges and their configuration.

General Steps

1. Choose a Bridge

   • Verify the bridge is compatible with Synapse.
   • Check if it has a Docker image available.
   • Review its documentation for specific requirements.

2. Add Database Support

   • Access the PostgreSQL container:

   docker compose exec postgres psql -U synapse
   

   • Create a new database and grant permissions:

   CREATE DATABASE your_bridge_name;
   GRANT ALL PRIVILEGES ON DATABASE your_bridge_name TO synapse;
   

   • Verify the database was created:

   \l
   

   • Exit the PostgreSQL prompt:

   \q
   

3. Update Docker Compose

   • Add a new service in docker-compose.yml:

   your-bridge-name:
     hostname: your-bridge-name
     image: repository/bridge-image:tag
     restart: no
     volumes:
       - ./config/mautrix-your-bridge:/data
       - /etc/localtime:/etc/localtime:ro
     depends_on:
       postgres:
         condition: service_healthy
     healthcheck:
       test: ["CMD-SHELL", "test -f /data/config.yaml -a -f /data/registration.yaml"]
       interval: 30s
       timeout: 10s
       retries: 1
       start_period: 5s
   

4. Create Bridge Configuration Directory

   mkdir -p config/mautrix-your-bridge
   

5. Configure the Bridge

   • Follow the bridge's official documentation for setup and configuration.
   • Common configuration points:
     • Database connection string.
     • Homeserver settings (using internal Docker network).
     • Bridge-specific authentication or API settings.
     • Permissions and access controls.
   • Make sure to generate any required registration files.
   • Update Synapse configuration to include the new bridge's registration file.

Integration Checklist

Use this checklist to ensure proper integration:

• Database created manually in PostgreSQL.
• Service added to docker-compose.yml.
• Configuration directory created.
• Tested with existing setup.
• Verified all dependencies.

Best Practices

1. Configuration Consistency

   • Follow the existing pattern for database names.
   • Use similar Docker Compose service definitions.
   • Maintain consistent volume mount paths.

2. Testing

   • Test the bridge in isolation first.
   • Verify interaction with existing bridges.
   • Check for potential port conflicts.
   • Validate database connectivity.

3. Security Considerations

   • Review bridge-specific security requirements.
   • Follow least-privilege principle for configurations.
   • Document any security-related settings.

Common Issues

1. Database Connection

   • Verify database name matches in all configurations.
   • Check database user permissions.
   • Ensure proper connection string format.

2. Docker Networking

   • Confirm service name resolution works.
   • Check for port conflicts.
   • Verify network dependencies.

3. Configuration Files

   • Ensure proper file permissions.
   • Validate YAML syntax.
   • Check for required configuration options.

Contributing

If you successfully integrate a new bridge, consider:

1. Documenting any special considerations.
2. Sharing your configuration templates.
3. Updating this guide with new insights.
4. Creating a pull request with your additions.

Next Steps

After adding a new bridge:

1. Test thoroughly with existing bridges.
2. Update your backup procedures.
3. Document any maintenance requirements.
4. Share your experience with the community.