matrix-docker-ansible-deploy/docs/configuring-playbook-base-domain-serving.md

Serving the base domain

This playbook sets up services on your Matrix server (matrix.DOMAIN). To have this server officially be responsible for Matrix services for the base domain (DOMAIN), you need to set up Server Delegation. This is normally done by configuring well-known files on the base domain.

People who don’t have a separate server to dedicate to the base domain have trouble arranging this.

Usually, there are 2 options:

• either get a separate server for the base domain, just for serving the files necessary for Server Delegation via a well-known file

• or, arrange for the Matrix server to serve the base domain. This either involves you using your own webserver or making the integrated webserver serve the base domain for you.

This documentation page tells you how to do the latter. With some easy changes, we make it possible to serve the base domain from the Matrix server via the integrated webserver.

Just adjust your DNS records, so that your base domain is pointed to the Matrix server’s IP address (using a DNS A record) and then use the following configuration:

matrix_static_files_container_labels_base_domain_enabled: true

Doing this, the playbook will:

• obtain an SSL certificate for the base domain, just like it does for all other domains (see how we handle SSL certificates)

• serve the /.well-known/matrix/* files which are necessary for Federation Server Discovery (also see Server Delegation) and Client-Server discovery

• serve a simple homepage at https://DOMAIN with content Hello from DOMAIN (configurable via the matrix_static_files_file_index_html_template variable). You can also serve a more complicated static website.

Serving a static website at the base domain

By default, when “serving the base domain” is enabled, the playbook hosts a simple index.html webpage at /matrix/static-files/public/index.html. The content of this page is taken from the matrix_static_files_file_index_html_template variable.

If you’d like to host your own static website (more than a single index.html page) at the base domain, you can disable the creation of this default index.html page like this:

# Enable base-domain serving
matrix_static_files_container_labels_base_domain_enabled: true

# Prevent the default index.html file from being installed
matrix_static_files_file_index_html_enabled: false

# Disable the automatic redirectin of `https://DOMAIN/` to `https://matrix.DOMAIN/`.
# This gets automatically enabled when you disable `matrix_static_files_file_index_html_enabled`, as we're doing above.
matrix_static_files_container_labels_base_domain_root_path_redirection_enabled: false

With this configuration, Ansible will no longer mess around with the /matrix/static-files/public/index.html file.

You are then free to upload any static website files to /matrix/static-files/public and they will get served at the base domain. You can do so manually or by using the ansible-role-aux Ansible role, which is part of this playbook already.

Serving a more complicated website at the base domain

If you’d like to serve an even more complicated (dynamic) website from the Matrix server, relying on the playbook to serve the base domain is not the best choice.

You have 2 options.

One way is to host your base domain elsewhere. This involves:

• you stopping to serve it from the Matrix server: remove matrix_static_files_container_labels_base_domain_enabled from your configuration
• configuring Matrix Delegation via well-known

Another way is to serve the base domain from another (your own) container on the Matrix server. This involves:

• telling the playbook to only serve BASE_DOMAIN/.well-known/matrix files by adjusting your vars.yml configuration like this:
  • keep matrix_static_files_container_labels_base_domain_enabled: true
  • add an extra: matrix_static_files_container_labels_base_domain_traefik_path_prefix: /.well-known/matrix
• building and running a new container on the Matrix server:
  • it should be connected to the traefik network, so that Traefik can reverse-proxy to it
  • it should have appropriate container labels, which instruct Traefik to reverse-proxy to it

How you’ll be managing building and running this container is up-to-you. You may use of the primitives from ansible-role-aux Ansible role to organize it yourself, or you can set it up in another way.