diff options
Diffstat (limited to 'README.rst')
| -rw-r--r-- | README.rst | 126 |
1 files changed, 126 insertions, 0 deletions
diff --git a/README.rst b/README.rst new file mode 100644 index 0000000000..a34e8bf2ac --- /dev/null +++ b/README.rst @@ -0,0 +1,126 @@ +Installation +============ + +[TODO(kegan): I also needed libffi-dev, which I don't think is included in build-essential.] + +First, the dependencies need to be installed. Start by installing 'python-dev' +and the various tools of the compiler toolchain: + + Installing prerequisites on ubuntu:: + + $ sudo apt-get install build-essential python-dev + + Installing prerequisites on Mac OS X:: + + $ xcode-select --install + +The homeserver has a number of external dependencies, that are easiest +to install by making setup.py do so, in --user mode:: + + $ python setup.py develop --user + +This will run a process of downloading and installing into your +user's .local/lib directory all of the required dependencies that are +missing. + +Once this is done, you may wish to run the homeserver's unit tests, to +check that everything is installed as it should be:: + + $ python setup.py test + +This should end with a 'PASSED' result:: + + Ran 143 tests in 0.601s + + PASSED (successes=143) + + +Running The Home Server +======================= + +In order for other home servers to send messages to your server, they will need +to know its host name. You have two choices here, which will influence the form +of your user IDs: + + 1) Use the machine's own hostname as available on public DNS in the form of its + A or AAAA records. This is easier to set up initially, perhaps for testing, + but lacks the flexibility of SRV. + + 2) Set up a SRV record for your domain name. This requires you create a SRV + record in DNS, but gives the flexibility to run the server on your own + choice of TCP port, on a machine that might not be the same name as the + domain name. + +For the first form, simply pass the required hostname (of the machine) as the +--host parameter:: + + $ python synapse/app/homeserver.py --host machine.my.domain.name + +For the second form, first create your SRV record and publish it in DNS. This +needs to be named _matrix._tcp.YOURDOMAIN, and point at at least one hostname +and port where the server is running. (At the current time we only support a +single server, but we may at some future point support multiple servers, for +backup failover or load-balancing purposes). The DNS record would then look +something like:: + + _matrix._tcp IN SRV 10 0 8448 machine.my.domain.name. + +At this point, you should then run the homeserver with the hostname of this +SRV record, as that is the name other machines will expect it to have:: + + $ python synapse/app/homeserver.py --host my.domain.name --port 8448 + +You may additionally want to pass one or more "-v" options, in order to +increase the verbosity of logging output; at least for initial testing. + + +Running The Web Client +====================== + +At the present time, the web client is not directly served by the homeserver's +HTTP server. To serve this in a form the web browser can reach, arrange for the +'webclient' sub-directory to be made available by any sort of HTTP server that +can serve static files. For example, python's SimpleHTTPServer will suffice:: + + $ cd webclient + $ python -m SimpleHTTPServer + +You can now point your browser at http://localhost:8000/ to find the client. + +If this is the first time you have used the client from that browser (it uses +HTML5 local storage to remember its config), you will need to log in to your +account. If you don't yet have an account, because you've just started the +homeserver for the first time, then you'll need to register one. + +Registering A New Account +------------------------- + +Your new user name will be formed partly from the hostname your server is +running as, and partly from a localpart you specify when you create the +account. Your name will take the form of:: + + @localpart:my.domain.here + (pronounced "at localpart on my dot domain dot here") + +Specify your desired localpart in the topmost box of the "Register for an +account" form, and click the "Register" button. + +Logging In To An Existing Account +--------------------------------- + +[[TODO(paul): It seems the current web client still requests an access_token - + I suspect this part will need updating before we can point people at how to + perform e.g. user+password or 3PID authenticated login]] + + +Building Documentation +====================== + +Before building documentation install spinx and sphinxcontrib-napoleon:: + + $ pip install sphinx + $ pip install sphinxcontrib-napoleon + +Building documentation:: + + $ python setup.py build_sphinx |