Skip to content
This repository has been archived by the owner on Apr 26, 2024. It is now read-only.

Commit

Permalink
Documentation improvements to contributing guide (#15667) (#15668)
Browse files Browse the repository at this point in the history
Fix #15667

 - Reiterate the importance of getting Rust installed and set up before attempting to install the Python dependencies.
 - Mention the importance of confirming that `poetry install` completed successfully and include a typical error that the user might see if it did not.
 - Expand on "Now edit homeserver.yaml" to give examples of things likely to need changing and to link to the relevant sections of the Synapse server documentation.
  • Loading branch information
grantm authored May 26, 2023
1 parent 2ad91ec commit 179f0f8
Show file tree
Hide file tree
Showing 2 changed files with 29 additions and 5 deletions.
1 change: 1 addition & 0 deletions changelog.d/15668.doc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Improve contributor docs to make it more clear that Rust is a necessary prerequisite. Contributed by @grantm.
33 changes: 28 additions & 5 deletions docs/development/contributing_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,9 @@ on Windows is not officially supported.

The code of Synapse is written in Python 3. To do pretty much anything, you'll need [a recent version of Python 3](https://www.python.org/downloads/). Your Python also needs support for [virtual environments](https://docs.python.org/3/library/venv.html). This is usually built-in, but some Linux distributions like Debian and Ubuntu split it out into its own package. Running `sudo apt install python3-venv` should be enough.

A recent version of the Rust compiler is needed to build the native modules. The
easiest way of installing the latest version is to use [rustup](https://rustup.rs/).

Synapse can connect to PostgreSQL via the [psycopg2](https://pypi.org/project/psycopg2/) Python library. Building this library from source requires access to PostgreSQL's C header files. On Debian or Ubuntu Linux, these can be installed with `sudo apt install libpq-dev`.

Synapse has an optional, improved user search with better Unicode support. For that you need the development package of `libicu`. On Debian or Ubuntu Linux, this can be installed with `sudo apt install libicu-dev`.
Expand All @@ -30,9 +33,6 @@ The source code of Synapse is hosted on GitHub. You will also need [a recent ver

For some tests, you will need [a recent version of Docker](https://docs.docker.com/get-docker/).

A recent version of the Rust compiler is needed to build the native modules. The
easiest way of installing the latest version is to use [rustup](https://rustup.rs/).


# 3. Get the source.

Expand All @@ -53,6 +53,11 @@ can find many good git tutorials on the web.

# 4. Install the dependencies


Before installing the Python dependencies, make sure you have installed a recent version
of Rust (see the "What do I need?" section above). The easiest way of installing the
latest version is to use [rustup](https://rustup.rs/).

Synapse uses the [poetry](https://python-poetry.org/) project to manage its dependencies
and development environment. Once you have installed Python 3 and added the
source, you should install `poetry`.
Expand All @@ -76,22 +81,40 @@ cd path/where/you/have/cloned/the/repository
poetry install --extras all
```

This will install the runtime and developer dependencies for the project.
This will install the runtime and developer dependencies for the project. Be sure to check
that the `poetry install` step completed cleanly.

## Running Synapse via poetry

To start a local instance of Synapse in the locked poetry environment, create a config file:

```sh
cp docs/sample_config.yaml homeserver.yaml
cp docs/sample_log_config.yaml log_config.yaml
```

Now edit homeserver.yaml, and run Synapse with:
Now edit `homeserver.yaml`, things you might want to change include:

- Set a `server_name`
- Adjusting paths to be correct for your system like the `log_config` to point to the log config you just copied
- Using a [PostgreSQL database instead of SQLite](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#database)
- Adding a [`registration_shared_secret`](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#registration_shared_secret) so you can use [`register_new_matrix_user` command](https://matrix-org.github.io/synapse/latest/setup/installation.html#registering-a-user).

And then run Synapse with the following command:

```sh
poetry run python -m synapse.app.homeserver -c homeserver.yaml
```

If you get an error like the following:

```
importlib.metadata.PackageNotFoundError: matrix-synapse
```

this probably indicates that the `poetry install` step did not complete cleanly - go back and
resolve any issues and re-run until successful.

# 5. Get in touch.

Join our developer community on Matrix: [#synapse-dev:matrix.org](https://matrix.to/#/#synapse-dev:matrix.org)!
Expand Down

0 comments on commit 179f0f8

Please sign in to comment.