diff --git a/docker/README.md b/docker/README.md index 8dba6fdb05..02ef5a94ec 100644 --- a/docker/README.md +++ b/docker/README.md @@ -243,3 +243,26 @@ healthcheck: Jemalloc is embedded in the image and will be used instead of the default allocator. You can read about jemalloc by reading the Synapse [Admin FAQ](https://element-hq.github.io/synapse/latest/usage/administration/admin_faq.html#help-synapse-is-slow-and-eats-all-my-ramcpu). + + +## Modules + +Synapse supports loading additional modules, using the +[`modules`](https://element-hq.github.io/synapse/latest/modules/index.html) +config. Synapse will look for these modules `/modules`. + +To install a package, simply run: + +``` +pip install --target +``` + +Where `` is the directory mounted to `/modules`, and +`` is either the package name or a path to the package. See +`pip install` for more details. + +**Note**: Packages already installed as part of Synapse cannot be overridden by +different versions of the package in `/modules`, e.g. if the Synapse version +uses Twisted 24.3.0 then installing Twisted 23.10.0 in `/modules` won't have any +effect. This can cause issues if the required version of a package is different +between Synapse and the module being installed. diff --git a/docker/start.py b/docker/start.py index 818a5355ca..bd0ef60420 100755 --- a/docker/start.py +++ b/docker/start.py @@ -269,6 +269,15 @@ running with 'migrate_config'. See the README for more details. args += ["--config-path", config_path] + # Add the `/modules` directly to python search path, which allows users to + # add custom modules. + # + # We want to add the directory *last* so that nothing can overwrite the + # existing package versions. Therefore we load the current path and append + # `/modules` to that + path = ":".join(sys.path) + environ["PYTHONPATH"] = f"{path}:/modules" + log("Starting synapse with args " + " ".join(args)) args = [sys.executable] + args