Proposal: Make installation docs more consistent and expand initial setup docs
I'm a brand new Matrix user with maybe a week of experience, so I thought I'd bring my perspective on the docs. I'd like to improve the installation documentation, but I'd like some feedback on the approach I'd like to take.
Current state of things
The current deployment documentation is a bit of a mixed bag:
The "generic" page is the most detailed, containing details on:
- Installing from binary
- Installing from .deb package
- Installing from source
- Forwarding ports
- Using delegation to use port 443 instead of 8448 for Cloudflare
- Creating config
- Reverse proxies
- Apache
- Caddy
- Nginx
- Testing the server using Matrix client or hitting
/_matrix/client/versions
A lot of these are useful for the other installation methods too.
The Docker page contains details on:
- Using
docker run
- Using Docker compose
- Using Traefik as reverse proxy
- Using Nginx to serve
.well-known/matrix/server
and.well-known/matrix/client
(which isn't actually specific to Docker) - Setting up Coturn
The Debian page references the generic page, but has a bit more info about Debian specifics.
The NixOS page is pretty short. It doesn't explain how to set up a reverse proxy.
Changes to make
The docs should have two separate sections:
Installation
The installation pages should only contain information specific to that particular installation method. This means no information about config files, reverse proxies, etc.
- Remove port forwarding, delegation, config, reverse proxies, and testing from generic page
- Remove Nginx from Docker page
- Maybe remove Coturn from Docker page - link to Coturn's Docker docs instead.
Initial Setup (name TBD)
This page would cover everything that's agnostic to the installation method - Configuration, set up, and testing. One page someone can follow regardless of how they install Conduit. For example:
- Explain domain names
- Matrix can either use same domain for both server and users (e.g. Conduit at
example.com
and users like@dan:example.com
), or use separate domain for server (e.g. Conduit atmatrix.example.com
, users like@dan:example.com
)- There can be an existing site on
example.com
-
example.com
andmatrix.example.com
can be totally separate servers - If Matrix server domain different to user domain, need to delegate via
.well-known
- How to create
.well-known
files depends on how theexample.com
site is set up
- How to create
- There can be an existing site on
- Domain for Matrix server can't easily be changed
- Recommend using separate subdomains when running web UI like Element (e.g.
matrix.example.com
andelement.example.com
) - this is so CORS policy works properly and prevents XSS attacks from UI to Matrix server
- Matrix can either use same domain for both server and users (e.g. Conduit at
- Reverse proxy setup
- Only
/_matrix
needs to be proxied
- Only
- Testing
- Hit
/_matrix/client/versions
in browser or via cURL - Matrix client
- Matrix Federation Tester
- Hit
- Initial user creation
- Need to allow user creation in config to create first user. Can disable user creation afterwards
Other changes
- Left nav should be rearranged to be in this order:
- Introduction
- Installation - Generic, Debian, Docker, NixOS
- Initial Setup - could cover basic config options
- Configuration - full list of all config options
Anything I'm missing? Any other suggestions?