# How To: Install a Matrix.org Home Server (net/py-matrix-synapse)



## TzunTzai (Feb 22, 2017)

*References & Links:*

Matrix.org
http://matrix.org
"Matrix is an open standard for interoperable, decentralised, real-time communication over IP. It can be used to power Instant Messaging, VoIP/WebRTC signalling, Internet of Things communication - or anywhere you need a standard HTTP API for publishing and subscribing to data whilst tracking the conversation history."

Synapse
net/py-matrix-synapse
https://github.com/matrix-org/synapse

Riot.im (Mobile Client)
https://riot.im


*My Thoughts*

Matrix.org is brilliant! I work for a small IT company. We like to keep things in house so we chose to host our own communication services via XMPP (OpenFire) for internal chat and mobile messaging as well as IRC (UnrealIRCd + ZNC) just to have it. When I stumbled across Matrix.org I was excited to try this new project. Synapse is still in heavy beta however, after using it I'm even more excited for whats to come.

I've written this tutorial for those of you who want to give a Matrix.org HomeServer a try.


*Lets Begin!*


Assuming you have a clean installation of FreeBSD 11

Switch to root user or use sudo
`su root`

Update FreeBSD
`freebsd-update fetch install`

Install Ports Tree
`portsnap fetch extract`

Install ports-mgmt/portmaster

```
# cd /usr/ports/ports-mgmt/portmaster
# make install clean
```

I use portmaster due to the number of dependencies, however you could just jump to the next step and use "make install clean"

Install net/py-matrix-synapse

```
# cd /usr/ports/net/py-matrix-synapse
# portmaster
```


Do note, you can also do an install via `pkg install py27-matrix-synapse` with Synth `pkg install synth` for keeping packages current... However, that's another tutorial.

Create directory for Synapse files. This can be done under your own account or you can create a synapse user. This is fine because Synapse does not require root/wheel permissions to run.

`mkdir ~/.synapse`


I created 3 scripts for the next three steps.


*Script #1*: synapse_config.sh
This will be used to configure synapse before starting the service.


```
#!/bin/sh
# Synapse: Config Synapse
cd ~/.synapse
python2.7 -m synapse.app.homeserver \
          --server-name  MyDomain.com \         # *MyDomain.com* can be any internal or external domain
          --config-path homeserver.yaml \
          --generate-config \
          --report-stats=no
```

For further details on this script, please visit Synapse on GitHub. For this tutorial, all you'll need to adjust is the domain. Save the script then run it to configure synapse. Which we'll do at this time.



```
# ~/synapse_config.sh
A config file has been generated in 'homeserver.yaml' for server name 'MyDomain.com' with corresponding SSL keys and self-signed certificates. Please review this file and customize it to your needs.
If this server name is incorrect, you will need to regenerate the SSL certificates
```



*Script #2*: synapse_start.sh
This script will be used to start Synapse. It will also be added to cron so it'll run at boot.


```
#!/bin/sh
# Synapse: Start Synapse
cd ~/.synapse
synctl start
```

Lets start Synapse then add this script to cron


```
# ~/synapse_start.sh
2017-02-21 22:06:39,476 - twisted - 131 - INFO - - SynapseSite starting on 8008
2017-02-21 22:06:39,477 - twisted - 131 - INFO - - Starting factory <synapse.http.site.SynapseSite instance at 0x80f17b680>
2017-02-21 22:06:39,477 - synapse.app.homeserver - 202 - INFO - - Synapse now listening on port 8008
started synapse.app.homeserver('homeserver.yaml')
```

The configuration should take a few seconds. Once done, you should see something similar to the text above.

Lets add this script to the cronjobs. Not as root.

```
# crontab -e
@reboot ~/synapse_start.sh
```


*Script #3*: synapse_add_user.sh
This script will be used to add users to the Synapse database.


```
#!/bin/sh
# Synapse: Add User
cd ~/.synapse
register_new_matrix_user -c homeserver.yaml https://localhost:8448
```

Lets run this script...

```
# ~/code/scripts/synapse_add_user.sh
New user localpart [tzuntzai]: tzuntzai
Password:
Confirm password:
Make admin [no]: yes
```

If everything goes well, you can point your browser to https://localhost:8448 and you’ll be presented with a login screen.

Use the account you just created to log into your Matrix.org Home Server and enjoy! Cheers!


~ Alex


----------



## dasti (Jun 15, 2017)

hi

This project is indeed very interesting ! 
I just tried to install it (0.21.0) with pkg, the installation is ok but when I try to use the configuration script I get this group or errors that seems to come from this line
`python2.7 -m synapse.app.homeserver`


```
$ ./synapse_config.sh
Traceback (most recent call last):
  File "/usr/local/lib/python2.7/runpy.py", line 174, in _run_module_as_main
    "__main__", fname, loader, pkg_name)
  File "/usr/local/lib/python2.7/runpy.py", line 72, in _run_code
    exec code in run_globals
  File "/usr/local/lib/python2.7/site-packages/synapse/app/homeserver.py", line 31, in <module>
    from synapse.rest import ClientRestResource
  File "/usr/local/lib/python2.7/site-packages/synapse/rest/__init__.py", line 20, in <module>
    from synapse.rest.client.v1 import (
  File "/usr/local/lib/python2.7/site-packages/synapse/rest/client/v1/pusher.py", line 23, in <module>
    from synapse.http.server import finish_request
  File "/usr/local/lib/python2.7/site-packages/synapse/http/server.py", line 31, in <module>
    from twisted.web import server, resource
  File "/usr/local/lib/python2.7/site-packages/twisted/web/server.py", line 31, in <module>
    from twisted.web import iweb, http, util
  File "/usr/local/lib/python2.7/site-packages/twisted/web/util.py", line 13, in <module>
    from twisted.python import urlpath
  File "/usr/local/lib/python2.7/site-packages/twisted/python/urlpath.py", line 15, in <module>
    from hyperlink import URL as _URL
ImportError: No module named hyperlink
./synapse_config.sh: --config-path: not found
```

Do you have any idea where I should start searching ? Or maybe I did a newbie mistake ? 

thanks
dasti


----------



## TzunTzai (Jun 16, 2017)

dasti said:


> hi
> 
> This project is indeed very interesting !
> I just tried to install it (0.21.0) with pkg, the installation is ok but when I try to use the configuration script I get this group or errors that seems to come from this line
> ...



Hi Dasti,

From my end, before configuring a homeserver, I make sure all my ports are up to date using ports-mgmt/synth/. I do not use PKG as I like to keep things current. Ports do this well.

Also, make sure there aren't any spaces in the script after "\"

With the error *"./synapse_config.sh: --config-path: not found*", you may want to verify that you're in the correct directory...


```
# Synapse: Config Synapse
cd ~/.synapse
python2.7 -m synapse.app.homeserver \
         --server-name  MyDomain.com \
          --config-path homeserver.yaml \
          --generate-config \
          --report-stats=no
```

In this case, the synapse folder containing all scripts is located on my home folder.

When running the scripts, be sure you're in the correct folder, or verify the script includes the "cd ~/.synapse " command before running.

*/usr/home/USERNAME/.synapse/ * <------ This script is designed to run in *.synapse* in your home folder.

Some time ago, I did run into a little issue with Python at first. But after running Synth or Portmaster to update my ports collection, the problem went away.

Hope this helps.


----------



## TzunTzai (Jun 18, 2017)

getopt said:


> This is a how-to isn't it? So I like to feedback on how you wrote your how-to.
> 
> 1. Update FreeBSD. What about building FreeBSD from source?
> 
> ...



Thank you for the feedback getopt . This How-To was only intended for the installation process of a Matrix.org Homesever itself, on FreeBSD. However, your suggestions are indeed important for those who would like help with a FreeBSD installation and ports from scratch. So I’ll add a few more links for those who are interested.


*Installing FreeBSD from scratch*
https://forums.freebsd.org/threads/59432/
or
http://www.all-nettools.com/forum/showthread.php?34422-Building-the-FreeBSD-OS-from-scratch

*Using Subversion to update Ports, src, and docs*
https://www.freebsd.org/doc/handbook/svn.html

*Updating Ports in FreeBSD using ports-mgmt/poudriere*
https://forums.freebsd.org/threads/38859/

*Updating Ports in FreeBSD using ports-mgmt/synth*
https://forums.freebsd.org/threads/54690/

Both Poudriere and Synth are great, however I'm pretty satisfied with Synth.


----------



## TzunTzai (Jun 18, 2017)

lol... obviously I didn't. Cheers!


----------



## dasti (Jun 19, 2017)

TzunTzai said:


> Hi Dasti,
> 
> From my end, before configuring a homeserver, I make sure all my ports are up to date using ports-mgmt/synth/. I do not use PKG as I like to keep things current. Ports do this well.
> 
> Also, make sure there aren't any spaces in the script after "\"




Thanks for your suggestions, I noticed that I indeed place the script in the wrong directory but the main error resists for now.


I did reinstall using portmaster -> same problem

I also tried the command line that is suggested in the installation message -> same result
[FONT=Courier New]/usr/local/bin/python2.7 -B -m synapse.app.homeserver -c /usr/local/etc/matrix-synapse/homeserver.yaml --generate-config --server-name=*example.com*[/FONT]​
starting the service also send the same error message

I also tried to copy the sampe config files from /usr/local/etc/matrix-synapse and start the server -> same result



```
Traceback (most recent call last):
  File "/usr/local/lib/python2.7/runpy.py", line 174, in _run_module_as_main
    "__main__", fname, loader, pkg_name)
  File "/usr/local/lib/python2.7/runpy.py", line 72, in _run_code
    exec code in run_globals
  File "/usr/local/lib/python2.7/site-packages/synapse/app/homeserver.py", line 31, in <module>
    from synapse.rest import ClientRestResource
  File "/usr/local/lib/python2.7/site-packages/synapse/rest/__init__.py", line 20, in <module>
    from synapse.rest.client.v1 import (
  File "/usr/local/lib/python2.7/site-packages/synapse/rest/client/v1/pusher.py", line 23, in <module>
    from synapse.http.server import finish_request
  File "/usr/local/lib/python2.7/site-packages/synapse/http/server.py", line 31, in <module>
    from twisted.web import server, resource
  File "/usr/local/lib/python2.7/site-packages/twisted/web/server.py", line 31, in <module>
    from twisted.web import iweb, http, util
  File "/usr/local/lib/python2.7/site-packages/twisted/web/util.py", line 13, in <module>
    from twisted.python import urlpath
  File "/usr/local/lib/python2.7/site-packages/twisted/python/urlpath.py", line 15, in <module>
    from hyperlink import URL as _URL
ImportError: No module named hyperlink
```



I had a quick look at which lines causes an error and it's respectively 

[FONT=Courier New]from synapse.rest import ClientRestResource
from synapse.rest.client.v1 import
from synapse.http.server import finish_request[/FONT]​


It seem to be a python problem, I think I'm going to open a bug report.

dasti


----------



## dasti (Jun 20, 2017)

This is caused by a bug in devel/py-twisted
https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=220120 --> https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=219993


----------

