# 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.