matrix-vanity/README.md

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

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:

{
	// 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, by setting up /.well-known/matrix/server (or picking one of the other methods if you prefer)

{
  "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.