etke.ccProper .well-known setup is a prerequisite for installing a Matrix server.
It is required not only for Matrix clients and servers, but also for the server admin panel, in-app calls, and other features.
You can either point your apex/base domain to the Matrix server IP address, or set up a few redirects on your apex/base domain.
This page covers the second option. It keeps usernames clean (without the matrix. prefix) while leaving your base domain available for other uses, such as hosting a website.
Here we collect configuration examples for various web servers and platforms to help you set up the necessary redirects.
If you don’t see your web server or platform listed here, please contact us for assistance!
Web Servers¶
Nginx¶
# This is your HTTPS-enabled server for your-server.com.
# Replace your-server.com with your Matrix server's base/apex domain.
server {
server_name your-server.com;
location ^~ /.well-known/matrix/ {
add_header Access-Control-Allow-Origin "*" always;
return 301 https://matrix.your-server.com$request_uri;
}
# other configuration
}
Apache2¶
# This is your HTTPS-enabled server for your-server.com.
# Replace your-server.com with your Matrix server's base/apex domain.
<VirtualHost *:443>
ServerName your-server.com
# Ensure mod_headers and mod_alias (or mod_rewrite) are enabled
<Location "/.well-known/matrix/">
Header always set Access-Control-Allow-Origin "*"
</Location>
RedirectMatch 301 ^/\.well-known/matrix/(.*)$ https://matrix.your-server.com/.well-known/matrix/$1
# other configuration
</VirtualHost>
Caddy 2¶
# This is your HTTPS-enabled frontend for your-server.com.
# Replace your-server.com with your Matrix server's base/apex domain.
your-server.com {
@matrixWellKnown path /.well-known/matrix/*
header @matrixWellKnown Access-Control-Allow-Origin "*"
redir @matrixWellKnown https://matrix.your-server.com{uri} 301
# other configuration
}
Platforms¶
Vercel¶
Configured in vercel.json, replace your-server.com with your Matrix server base/apex domain:
{
"headers": [
{
"source": "/.well-known/matrix/(.*)",
"headers": [
{
"key": "Access-Control-Allow-Origin",
"value": "*"
}
]
}
],
"redirects": [
{
"source": "/.well-known/matrix/server",
"destination": "https://matrix.your-server.com/.well-known/matrix/server",
"statusCode": 301
},
{
"source": "/.well-known/matrix/client",
"destination": "https://matrix.your-server.com/.well-known/matrix/client",
"statusCode": 301
},
{
"source": "/.well-known/matrix/support",
"destination": "https://matrix.your-server.com/.well-known/matrix/support",
"statusCode": 301
}
]
}