cqrenet/mxids
3
0
Fork 0
Code Pull Requests 10 Actions Releases Activity

Documentation enhancements (#73)

Browse Source
This commit is contained in:
Max Dor
2018-04-13 03:26:33 +02:00
committed by GitHub
parent 1e413af019
commit ef80f4aa30
36 changed files with 970 additions and 1016 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
docs/getting-started.md
View File

@@ -7,19 +7,18 @@
6. [Next steps](#next-steps)
Following these quick start instructions, you will have a basic setup that can perform recursive/federated lookups and
talk to the central Matrix.org Identity service.
This will be a good ground work for further integration with your existing Identity stores.
talk to the central Matrix.org Identity server.
This will be a good ground work for further integration with features and your existing Identity stores.
## Preparation
You will need:
- Homeserver
- Reverse proxy with regular TLS/SSL certificate (Let's encrypt) for your mxisd domain
As synapse requires an HTTPS connection when talking to an Identity service, a reverse proxy is required as mxisd does
As synapse requires an HTTPS connection when talking to an Identity service, **a reverse proxy is required** as mxisd does
not support HTTPS listener at this time.
For maximum integration, it is best to have your Homeserver and mxisd reachable via the same hostname.
You can also use a dedicated domain for mxisd, but will not have access to some features.
For maximum integration, it is best to have your Homeserver and mxisd reachable via the same hostname.
Be aware of a [NAT/Reverse proxy gotcha](https://github.com/kamax-io/mxisd/wiki/Gotchas#nating) if you use the same
hostname.
@@ -37,16 +36,16 @@ Install via:
See the [Latest release](https://github.com/kamax-io/mxisd/releases/latest) for links to each.
## Configure
**NOTE**: please view the install instruction for your platform, as this step might be optional/handled for you.
**NOTE**: please view the install instruction for your platform, as this step might be optional or already handled for you.
Create/edit a minimal configuration (see installer doc for the location):
```
matrix.domain: 'MyMatrixDomain.org'
```yaml
matrix.domain: 'example.org'
key.path: '/path/to/signing.key.file'
storage.provider.sqlite.database: '/path/to/mxisd.db'
```
- `matrix.domain` should be set to your Homeserver domain
- `key.path` will store the signing keys, which must be kept safe!
- `matrix.domain` should be set to your Homeserver domain (`server_name` in synapse configuration)
- `key.path` will store the signing keys, which must be kept safe! If the file does not exist, keys will be generated for you.
- `storage.provider.sqlite.database` is the location of the SQLite Database file which will hold state (invites, etc.)
If your HS/mxisd hostname is not the same as your Matrix domain, configure `server.name`.
@@ -59,20 +58,20 @@ For an overview of a typical mxisd infrastructure, see the [dedicated document](
In the `VirtualHost` section handling the domain with SSL, add the following and replace `0.0.0.0` by the internal
hostname/IP pointing to mxisd.
**This line MUST be present before the one for the homeserver!**
```
ProxyPass /_matrix/identity/ http://0.0.0.0:8090/_matrix/identity/
```apache
ProxyPass /_matrix/identity http://0.0.0.0:8090/_matrix/identity
```
Typical configuration would look like:
```
```apache
<VirtualHost *:443>
ServerName example.org
...
ProxyPreserveHost on
ProxyPass /_matrix/identity/ http://localhost:8090/_matrix/identity/
ProxyPass /_matrix/ http://localhost:8008/_matrix/
ProxyPass /_matrix/identity http://localhost:8090/_matrix/identity
ProxyPass /_matrix http://localhost:8008/_matrix
</VirtualHost>
```
@@ -80,14 +79,14 @@ Typical configuration would look like:
In the `server` section handling the domain with SSL, add the following and replace `0.0.0.0` with the internal
hostname/IP pointing to mxisd.
**This line MUST be present before the one for the homeserver!**
```
```nginx
location /_matrix/identity {
proxy_pass http://0.0.0.0:8090/_matrix/identity;
}
```
Typical configuration would look like:
```
```nginx
server {
listen 443 ssl;
server_name example.org;
@@ -110,37 +109,27 @@ server {
### Synapse
Add your mxisd domain into the `homeserver.yaml` at `trusted_third_party_id_servers` and restart synapse.
In a typical configuration, you would end up with something similair to:
```
In a typical configuration, you would end up with something similar to:
```yaml
trusted_third_party_id_servers:
- matrix.org
- vector.im
- example.org
```
It is recommended to remove `matrix.org` and `vector.im` so only your own Identity server is authoritative for your HS.
It is recommended to remove `matrix.org` and `vector.im` (or any other default entry) from your configuration so only
your own Identity server is authoritative for your HS.
## Validate
Log in using your Matrix client and set `https://example.org` as your Identity server URL, replacing `example.org` by
the relevant hostname which you configured in your reverse proxy.
Invite `mxisd-lookup-test@kamax.io` to a room, which should be turned into a Matrix invite to `@mxisd-lookup-test:kamax.io`.
**NOTE:** you might not see a Matrix suggestion for the e-mail address, which is normal. Still proceed with the invite.
Invite `mxisd-federation-test@kamax.io` to a room, which should be turned into a Matrix invite to `@mxisd-lookup-test:kamax.io`.
At this point, the test user will join the room, send a congratulation message and leave.
**NOTE:** You might not see a suggestion for the e-mail address, which is normal. Still proceed with the invite.
If it worked, it means you are up and running and can enjoy mxisd in its basic mode! Congratulations!
If it did not work, [get in touch](#support) and we'll do our best to get you started.
You can now integrate mxisd further with your infrastructure using the various [features](README.md) guides.
If it did not work, [get in touch](../README.md#support) and we'll do our best to get you started.
## Next steps
Once your mxisd server is up and running, here are the next steps to further enhance and integrate your installation:
Once your mxisd server is up and running, there are several ways you can enhance and integrate further with your
infrastructure:
Enable extra features:
- [Federation](features/federation.md)
- [Authenticate with synapse](features/authentication.md), profile auto-provisioning if you wish
- [Directory search](features/directory-users.md)
Use your Identity stores:
- [LDAP / Samba / Active directory](backends/ldap.md)
- [SQL Database](backends/sql.md)
- [Website / Web service / Web app](backends/rest.md)
- [Google Firebase](backends/firebase.md)
- [Wordpress](backends/wordpress.md)
- [Enable extra features](features/)
- [Use your own Identity stores](stores/README.md)