We really *really* need a definitive guide on how to set up a homeserver/synapse

[turt2live]

I'm sure this is a duplicate of several issues, both in this repo and elsewhere.

There's not a day that goes by that someone inevitably walks into a support room asking why federation doesn't work, or how they can get Let's Encrypt working with federation, or wondering why synapse has two ports it opens (8008 and 8448). There are various guides out there that have a wide range of different opinions on the subject, some recommending the wrong thing and leading to more support load. It's worth noting that much of this support load is fronted by the community, who I'm sure would rather be making the ecosystem a better place than troubleshooting synapse day in and day out.

There's also been some issues raised in the past about similar questions, including the popular synapse issue: matrix-org/synapse#2438.

Currently there's no easy to find matrix.org-published guide on the subject, and it'd be nice to have the recommended guide reach the top of the search results.

Some things the guide should address are:

• A diagram of the infrastructure (:8448 to the world w/ self signed certs, :8008 localhost, :443 proxying to 8008 using Let's Encrypt)
• Explanation as to why it's a bad idea to use Let's Encrypt certificates for :8448, and why certificate errors are actually perfectly safe
• How to set/pick a server_name for synapse, and how that relates to your public domain record/DNS. For instance, it'd be a good idea to set up an SRV record regardless of the redundancy because it makes moving the server later easier, and it gives more permissive vanity domain names.
• How to test that everything is working
• A note to not be worried about signature errors when joining rooms, timeouts from random domain names, and failed requests to random domain names.

The guide should also show how the reverse proxy works, potentially even going a step further and implying that it's required. Could show how to install $web_client on the server as well. I'd highly recommend nginx because it's fast enough, not complicated to set up, and forgiving when it comes to formatting errors in the config (except semicolons). Compared to apache which is mostly XML based or HAProxy which is just complicated.

[richvdh]

omg yes.

[turt2live]

also the guide should cover how to set up postgres and ignore the fact that sqlite exists.

[joenas]

If it’s of any help I’ve got a blog post with a guide using Docker that you’re welcome to use. Assuming it’s correct...

EDIT: Here's the link

EDIT 2: Link for Synapse v1.0.0

[richvdh]

https://www.howtoforge.com/tutorial/how-to-install-matrix-synapse-on-ubuntu-1804/ is actually pretty good, modulo the fact that it firewalls the federation port.

[benparsons]

@richvdh did you find that via https://matrix.org/docs/guides/ ?

I'm trying to contact the author. If we can make the changes to the federation section, we could link to this from higher up on that page.

[richvdh]

@richvdh did you find that via https://matrix.org/docs/guides/ ?

No, somebody linked to it in some bug report or other.

[aaronraimist]

I know there is no priority labels in this repo but this issue needs to be p1. Lots of bad guides spreading around. A good official guide needs to be written ASAP.

[natrius]

@benparsons
I took that guide, edited it, changed some things because some things were not clear to me. If there are additional things to change about the federation and so on, i would be happy to change it too. I could give it to you to proof-read or something like that. I will upload it soon on my dokuwiki, if you like that idea.

[benparsons]

@natrius I like that idea very much! Can you share what you have here?

[natrius]

@benparsons
Of course: https://www.natrius.eu/dokuwiki/doku.php?id=digital:server:matrixsynapse

I could use some information about postgre ( i think i got that), the federation and the "no subdomain"-part. Will try today something new.

Discussions here or with messenger or a new issue? Otherwise, just contact me via @natrius:matrix.org

[benparsons]

@turt2live @richvdh @erikjohnston

@natrius has been working on a Synapse Installation guide, which has evolved significantly this week.

Can I ask for your eyes and feedback on https://www.natrius.eu/dokuwiki/doku.php?id=digital:server:matrixsynapse ?

If this is considered to be a good template, we can start to integrate the suggestions in @turt2live's first comment on this issue.

[turt2live]

Looks like a good start to me! Thank you for putting in the effort to make everything better.

I'd recommend removing the Ubuntu sysadmin tips as it adds a bit of confusion (ie: the stuff about sudo). For software-properties-common, I'd just make it look non-optional as a command. The worst that happens is the user spends 2 minutes watching something say "you already have this".

The guide should also probably just go straight into "use with a subdomain" instead of having the user figure out what they want.

There's a small missing step in the guide: When setting up the reverse proxy, the listener should be set to be bound to 127.0.0.1 instead of the default 0.0.0.0. Also, it should make sure to set the flag for recognizing the X-Forwarded-For header.

From the guide:

Port 8448 or 8008? In the readme its 8448, in a lot of other guides its 8008.

http://localhost:8008 is the one you're looking for.

[richvdh]

Indeed, looks like a great start! [I would point out that Synapse is called "Synapse", not "Matrix Synapse", though: the package is just matrix-synapse to distinguish it from another "synapse"...]

Towards the bottom you suggest installing things into the system python libraries with pip. In my experience, this is invariably a terrible idea.

My main concern at this stage would be: how specific to Ubuntu/Debian do we want this guide to be? There's a bunch of stuff in his guide which is quite specific to those OSes, so if we can't make it more generic, I guess we might end up with a guide for each OS :/.

[natrius]

@turt2live @richvdh @erikjohnston

I agree with some, but its called "on Ubuntu 18.04" and so i would like to leave it like that and not make one universal (imho they tend to get bloated). But i'm open for suggestions.

What i changed already because i think its good:
From "Matrix Synapse" to "Synapse", corrected the port for registering, removed the "pip installer" (i thought already that these are bad :D), made the install-add-repository-package non-optional and added the listener ports and removed the optional-admin-part.

I thought "Also, it should make sure to set the flag for recognizing the X-Forwarded-For header." that this is already done. About the subdomain, should i change that too?

[benparsons]

I agree it would be good to identify which parts can be extracted out so we can have little sections where the different distros diverge. This is good right now though with the changes made.

Next steps:

• link to this from matrix.org and get broader feedback
• collate all the suggestions from this task so we can know what to focus improvements on

(both of these are for me)

[databaze]

I'm new to Matrix & Synapse and I agree that the guides are all over the place.
I followed a few guides to install on Debian 8 and Ubuntu 18.04 and I always had issues. Granted I am new to linux but I found that most issues were related to the guide not being updated. In some cases when it stated for example "apt-get install matrix-synapse -y" I constantly get "unable to locate package" even with repositories added to sources.list & sources.list.d/matrix.list.
Another issue that I encountered was with what "flavor" of Debian or Ubuntu I should work with. Ubuntu server or desktop? Debian gnome or another? i386 or amd64 when running on a virtual environment, is it the same for vmware than virtual box? etc.
I tried with Ubuntu Server and I ran into all kinds of issues with pulling from repos the "matrix-synapse" package as well as with Debian, and there is NOTHING online that points to a solution. If i ever get it to work I will write a guide myself on how I got it running for people that may not be experts in linux and may want to learn as they go. I am going to record the process I went over with each distro and the moment I got stuck while following the guides, maybe it will show how one can get stuck while trying to get it to work.

[natrius]

@databaze
Out of curiosity, how did you find all the guides? Did you also consult https://matrix.org/docs/guides/ where two guides are recommended? For one, maybe the easier one, the docker one: https://github.com/matrix-org/synapse/tree/master/docker and the second one (i posted it up here in this issue), which can also found up here (https://matrix.org/docs/guides/installing-synapse).
If you have problems with my guide, please feel free to join the channel and tell me more or join directly #synapse-admins:matrix.org where some guys are around who really know what to do.

[databaze]

natrius,
I'm now following the guide for Ubuntu 18.04 on that list. Previously I followed these ones:

Ubuntu: https://www.howtoforge.com/tutorial/how-to-install-matrix-synapse-on-ubuntu-1804/

Debian: https://blog.cryptoaustralia.org.au/2017/03/21/run-your-end-to-end-encrypted-chat-server-matrix-riot/

I also tried to get it to work with these guides I found around the web:

https://steemit.com/synapse/@ubinodes/how-to-run-an-end-to-end-encrypted-chat-server-using-matrix-and-riot

https://dzone.com/articles/how-to-create-a-chat-server-using-matrix-synapse-o

https://xo.tc/seting-up-matrix-synapse-and-riot-on-debian-8-jessie.html

I will post after I am done trying your way, at the moment I am installing Ubuntu-18.04.1-desktop-amd64.iso and also ubuntu-18.04.1.0-live-server-amd64.iso both under vmware vsphere 6.5 environment.
Will join the channel right after, thanks for the reply.

[kewball]

[A comment on grammar & usage] at https://matrix.org/docs/guides/ I see something like this:
We recommend following this inline link to the good stuff but right now you need to look at this long list of false starts, incomplete instructions and old ideas.
Would it not be clearer to put "matrix-docker-ansible-deploy" and "Installation guide for Ubuntu" right here, by themselves, directly under the heading "Installing Synapse" -- and relegate the long list of despair to the sub-page?

[benparsons]

I believe we are happier now than we were, with the links starting from https://matrix.org/docs/guides/installing-synapse.

@turt2live @richvdh to reopen if needed

[rendaw]

I'm not sure what the end result of this ticket was, but I'm new to Matrix and the best documentation still seems to be matrix-org/synapse#2438 which I only found after getting confused after setting up a home server. The linked installing synapse guides don't have any information about port 443 forwarding to 8008, DNS, etc. AFAICT.

Most of the info in that ticket and the this one isn't homeserver specific and is important info for people setting up any home server, including dendrite and conduit I think. Would it be possible to document this somewhere prominently?

FWIW googling matrix home server ports, and with similar searches, the only official result is the FAQ which talks about federation ports only. There may be documentation I missed, but none of the titles in the guides section seemed relevant.

Since this isn't about synapse specifically I'd be glad to open a new issue if that would help.

[LinAGKar]

Does @richvdh's recommendation still stand? Because that's directly contradicted by https://github.com/matrix-org/synapse/blob/develop/docs/delegate.md#should-i-use-a-reverse-proxy-for-federation-traffic

[natrius]

As richvdhs post you linked is from 2017 i'm pretty sure you should take the one in the docs.

[LinAGKar]

I suppose so. Did some further digging, and the recommendation changed with Synapse 1.0 when they started requiring a signed certificate.

[JesseKPhillips]

I just completed setting up connection to the federation, and want to leave this here for others and hopes I'll come back to see if I could to a PR somewhere. My journey started with the docker-compose file and the issue I faced was that I couldn't add matrix.org to explore rooms. In my attempts to address this I went through a number of failures like

• http 401 - 401 Unauthorized when getting public room list synapse#7762
  • 401 Unauthorized only when trying to federate with matrix.org synapse#7764
• http 502 - Sent messages to the wrong location (port 8448)
• SynapseError: 502 - Failed to fetch room list - Failed to fetch room list synapse#12253
• Synapse refuses to federate with servers which return SERVFAIL for their SRV record synapse#6589
• Cannot start Synapse through docker-compose: Permission denied: '/data/homeserver.yaml' synapse#15202

And with that I went through a number of setup documents (list is probably not exhaustive)

• https://github.com/element-hq/synapse/tree/develop/contrib/docker
• https://element-hq.github.io/synapse/latest/setup/installation.html
• https://hub.docker.com/r/matrixdotorg/synapse
• Clarify recommended setup synapse#2438
• https://github.com/element-hq/synapse/blob/develop/docker/README.md

And of course there is context to why I might be struggling to get this working.

• I was already hosting NextCloud AIO and utilizing their auto LetsEncrypt against my dynu domain. I needed to get a reverse-proxy configured to add services.
• I'm using Caddy as my reverse-proxy
• I needed to have matrix on a subdomain, but I liked the idea of only needing @user:
• I decided to buy a domain name and switch after getting matrix configured
• These are mostly new things I've not worked with before

The primary failure point I ran into was trying to utilize this 8448 port that gets discussed. I was trying to get the federation to communicate to the docker container at this port and it really needed to talk to 8008. I didn't end up figuring out how to set my SRV DNS record correctly, here is what I did do.

I told caddy to specify a subdomain and port for the well-known server which ensures the SRV lookup is bypassed.

https://<domain>:443 {
    # Matrix WellKnown Delegation
    respond /.well-known/matrix/server 200 {
        body "{ \"m.server\": \"matrix-fed.<domain>:443\" }"
    }

And I delegated that to port 8008 (this is where I wrongly kept trying to get it to talk to port 8448 of the docker container).

# Matrix Delegation
matrix-fed.<domain>:443 {
    reverse_proxy localhost:8008
}

And I probably didn't need this layer since it is the same as:

# Matrix
chat.<domain>:443 {
    reverse_proxy localhost:8008
}

To round this all off I have added but not tested:

https://<domain>:443 {
#...
    respond /.well-known/matrix/client 200 {
        body "{ \"m.homeserver\": { \"base_url\": \"chat.<domain>\" }}"
    }

I hope to take this further into the documentation, but I just needed it publicly written down while I have it fresh in my head.