58 lines
2.1 KiB
Markdown
58 lines
2.1 KiB
Markdown
# Matrix-Vanity - Vanity names for Matrix rooms
|
|
|
|
This is an absolute bare minimum Matrix server implementation designed
|
|
to do one thing and one thing only: Enable you to give rooms vanity names
|
|
without running a homeserver
|
|
|
|
It handles just the room lookup by name endpoint, which is all that is needed
|
|
for this purpose. Perhaps in the future it will implement the room directory
|
|
as well, but for now it does not.
|
|
|
|
## Installation
|
|
[Deploy using the Docker images](https://git.alioth.systems/erin/-/packages/container/matrix-vanity/0.1),
|
|
or by building in the usual way for a Go project (`go build`) and deploying
|
|
via your preferred service orchestration system.
|
|
|
|
Pick a hostname and port that you will run this on. Organize for matrix-vanity
|
|
to run behind a TLS terminating proxy (it does not handle TLS itself)
|
|
|
|
Create a JSON file defining rooms:
|
|
```js
|
|
{
|
|
// Alias
|
|
"#matrix:example.com": {
|
|
// Room ID, from the Advanced tab of the room settings in Element
|
|
"room_id": "!OGEhHVWSdvArJzumhm:matrix.org",
|
|
// Pick one or more of the homeservers which host the room
|
|
"servers": ["matrix.org"]
|
|
}
|
|
}
|
|
|
|
```
|
|
|
|
When starting the server, set the following environment variables:
|
|
|
|
* `MXV_ROOMS_FILE` to the path to your room definition file,
|
|
* `MXV_USE_PROXY_HEADERS` if you wish to have the service interpret X-Forwarded-For
|
|
(only used for log output)
|
|
* `MXV_LISTEN` to your preferred listening spec (Default: `:3333`)
|
|
|
|
Check things are running, and that you have TLS certificates configured.
|
|
|
|
Delegate Matrix server-to-server handling for your hostname to this instance
|
|
[per the spec](https://spec.matrix.org/v1.8/server-server-api/#resolving-server-names),
|
|
by setting up `/.well-known/matrix/server` (or picking one of the other methods if you
|
|
prefer)
|
|
|
|
```json
|
|
{
|
|
"m.server": "matrix-vanity.example.com:443"
|
|
}
|
|
```
|
|
(Remember that if you don't specify a port, the default is 8448)
|
|
|
|
Now for each of your rooms for which you wish to advertise this alias, go to the room's
|
|
Visibility settings page in Element and enter the address in the "Other published addresses"
|
|
field. If all is configured properly, it should turn green. You can then make it the main
|
|
address if you wish.
|