diff --git a/INSTALL.md b/INSTALL.md index 2df686b19b07..25343593d529 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,3 +1,4 @@ +- [Choosing your server name](#choosing-your-server-name) - [Installing Synapse](#installing-synapse) - [Installing from source](#installing-from-source) - [Platform-Specific Instructions](#platform-specific-instructions) @@ -10,6 +11,22 @@ - [Setting up a TURN server](#setting-up-a-turn-server) - [URL previews](#url-previews) +# Choosing your server name + +It is important to choose the name for your server before you install Synapse, +because it cannot be changed later. + +The server name determines the "domain" part of user-ids for users on your +server: these will all be of the format `@user:my.domain.name`. It also +determines how other matrix servers will reach yours for federation. + +For a test configuration, set this to the hostname of your server. For a more +production-ready setup, you will probably want to specify your domain +(`example.com`) rather than a matrix-specific hostname here (in the same way +that your email address is probably `user@example.com` rather than +`user@email.example.com`) - but doing so may require more advanced setup: see +[Setting up Federation](docs/federate.md). + # Installing Synapse ## Installing from source @@ -64,16 +81,7 @@ python -m synapse.app.homeserver \ --report-stats=[yes|no] ``` -... substituting an appropriate value for `--server-name`. The server name -determines the "domain" part of user-ids for users on your server: these will -all be of the format `@user:my.domain.name`. It also determines how other -matrix servers will reach yours for Federation. For a test configuration, -set this to the hostname of your server. For a more production-ready setup, you -will probably want to specify your domain (`example.com`) rather than a -matrix-specific hostname here (in the same way that your email address is -probably `user@example.com` rather than `user@email.example.com`) - but -doing so may require more advanced setup: see [Setting up Federation](docs/federate.md). -Beware that the server name cannot be changed later. +... substituting an appropriate value for `--server-name`. This command will generate you a config file that you can then customise, but it will also generate a set of keys for you. These keys will allow your Home Server to @@ -86,9 +94,6 @@ different. See the [spec](https://matrix.org/docs/spec/server_server/latest.html#retrieving-server-keys) for more information on key management.) -You will need to give Synapse a TLS certficate before it will start - see [TLS -certificates](#tls-certificates). - To actually run your new homeserver, pick a working directory for Synapse to run (e.g. `~/synapse`), and:: diff --git a/changelog.d/5558.misc b/changelog.d/5558.misc new file mode 100644 index 000000000000..9ce3555d4559 --- /dev/null +++ b/changelog.d/5558.misc @@ -0,0 +1 @@ +Improve install docs on choosing server_name.