Add guide for integrating new Matrix bridges

ADDING_BRIDGES.md

@@ -0,0 +1,133 @@
+# Adding New Bridges Guide
+
+This guide explains how to integrate additional Matrix bridges into your Dendrite 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 Dendrite 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 Dendrite.
+   - Check if it has a Docker image available.
+   - Review its documentation for specific requirements.
+
+2. **Add Database Support**
+   - Access the PostgreSQL container:
+   ```bash
+   docker compose exec postgres psql -U dendrite
+   ```
+   - Create a new database and grant permissions:
+   ```sql
+   CREATE DATABASE your_bridge_name;
+   GRANT ALL PRIVILEGES ON DATABASE your_bridge_name TO dendrite;
+   ```
+   - Verify the database was created:
+   ```sql
+   \l
+   ```
+   - Exit the PostgreSQL prompt:
+   ```sql
+   \q
+   ```
+
+3. **Update Docker Compose**
+   - Add a new service in `docker-compose.yml`:
+   ```yaml
+   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**
+   ```bash
+   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 Dendrite's 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.

README.md

@@ -91,6 +91,9 @@ The script will:
 
 You can run this script multiple times to create additional users as needed.
 
+For information about adding additional bridges to your setup:
+- [Adding New Bridges](./ADDING_BRIDGES.md)
+
 ## Bridge Setup
 
 Each bridge starts in a stopped state and will only run once properly configured. You can configure the bridges in any order: