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

A first pass at pruning the Synapse README #13491

Merged
merged 22 commits into from
Aug 17, 2022
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 0 additions & 83 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -260,89 +260,6 @@ Alongside all that, join our developer community on Matrix:
`#synapse-dev:matrix.org <https://matrix.to/#/#synapse-dev:matrix.org>`_, featuring real humans!


Quick start
-----------
DMRobertson marked this conversation as resolved.
Show resolved Hide resolved

Before setting up a development environment for synapse, make sure you have the
system dependencies (such as the python header files) installed - see
`Platform-specific prerequisites <https://matrix-org.github.io/synapse/latest/setup/installation.html#platform-specific-prerequisites>`_.

To check out a synapse for development, clone the git repo into a working
directory of your choice::

git clone https://github.com/matrix-org/synapse.git
cd synapse

Synapse has a number of external dependencies. We maintain a fixed development
environment using `Poetry <https://python-poetry.org/>`_. First, install poetry. We recommend::

pip install --user pipx
pipx install poetry

as described `here <https://python-poetry.org/docs/#installing-with-pipx>`_.
(See `poetry's installation docs <https://python-poetry.org/docs/#installation>`_
for other installation methods.) Then ask poetry to create a virtual environment
from the project and install Synapse's dependencies::

poetry install --extras "all test"

This will run a process of downloading and installing all the needed
dependencies into a virtual env.

We recommend using the demo which starts 3 federated instances running on ports `8080` - `8082`::

poetry run ./demo/start.sh

(to stop, you can use ``poetry run ./demo/stop.sh``)

See the `demo documentation <https://matrix-org.github.io/synapse/develop/development/demo.html>`_
for more information.

If you just want to start a single instance of the app and run it directly::

# Create the homeserver.yaml config once
poetry run synapse_homeserver \
--server-name my.domain.name \
--config-path homeserver.yaml \
--generate-config \
--report-stats=[yes|no]

# Start the app
poetry run synapse_homeserver --config-path homeserver.yaml


Running the unit tests
----------------------

After getting up and running, you may wish to run Synapse's unit tests to
check that everything is installed correctly::

poetry run trial tests

This should end with a 'PASSED' result (note that exact numbers will
differ)::

Ran 1337 tests in 716.064s

PASSED (skips=15, successes=1322)

For more tips on running the unit tests, like running a specific test or
to see the logging output, see the `CONTRIBUTING doc <CONTRIBUTING.md#run-the-unit-tests>`_.


Running the Integration Tests
-----------------------------

Synapse is accompanied by `SyTest <https://github.com/matrix-org/sytest>`_,
a Matrix homeserver integration testing suite, which uses HTTP requests to
access the API as a Matrix client would. It is able to run Synapse directly from
the source tree, so installation of the server is not required.

Testing with SyTest is recommended for verifying that changes related to the
Client-Server API are functioning correctly. See the `SyTest installation
instructions <https://github.com/matrix-org/sytest#installing>`_ for details.


Platform dependencies
=====================

Expand Down