diff --git a/ADDING_BRIDGES.md b/ADDING_BRIDGES.md new file mode 100644 index 0000000..c108f89 --- /dev/null +++ b/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. diff --git a/README.md b/README.md index 96d4de4..16f5e40 100644 --- a/README.md +++ b/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: