Host Element Web on Nginx with a Custom Homeserver

To host a custom Element Web client on Nginx, download an official prebuilt Element Web release, place its static files on your web server, configure config.json with your Matrix homeserver, and serve the site over HTTPS. Nginx does not run Element itself: it serves the browser app files, while the app connects separately to your Matrix homeserver. Use a different hostname for the client and homeserver, such as chat.example.com and matrix.example.com.

This guide assumes Debian or Ubuntu, an Nginx server with a public DNS name, and an existing Matrix homeserver reachable over HTTPS. It uses the official release archive rather than a development build. Element's current project documentation describes the deployed web app as static content and requires key configuration and entry-point URLs to avoid caching. Check the release notes and current configuration documentation when choosing a release or changing options.

1. Prepare the hostname and server

Create an A record for chat.example.com pointing to the Nginx server's public IPv4 address. Add an AAAA record only if the server is reachable over IPv6. Allow inbound TCP ports 80 and 443 through the host firewall and cloud firewall. Confirm that these ports are not already occupied by another web server.

Install Nginx and create a directory for the web app:

sudo apt update
sudo apt install nginx
sudo mkdir -p /var/www/element

On another machine, open the official Element Web releases page and choose a published stable release. Download its prebuilt web archive, then transfer the archive to the server. Avoid using the develop branch or a nightly build for a public service unless you intend to run preview software.

2. Install the static files and set the homeserver

Extract the release archive into a temporary directory first. Inspect the archive's top-level layout, then copy its web files into /var/www/element; preserve the release's directory structure. The package layout can change, so make sure index.html, the bundles, i18n, and the configuration file land where Nginx's document root will point.

sudo mkdir -p /tmp/element-release
tar -xzf /tmp/element-web-REPLACE_WITH_RELEASE.tar.gz -C /tmp/element-release
find /tmp/element-release -maxdepth 2 -name index.html

Use the directory containing index.html as the source when copying the release contents to /var/www/element. If the archive has one versioned top-level directory, copy the contents of that directory rather than creating an extra nested level. Do not replace a live deployment until the new files are complete; an incomplete copy can leave users with missing JavaScript bundles.

Copy the release's config.sample.json to config.json if the archive provides it, then edit the new file. Element needs a default homeserver connection setting to start. The supported preferred form is default_server_config, using the base URL of the client API. The example below is illustrative; replace the URL with the actual URL served by your Matrix homeserver:

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.example.com"
    }
  },
  "brand": "Example Chat"
}

Element's configuration documentation also supports default_server_name, which relies on Matrix .well-known discovery. Use default_server_config when you want to specify the homeserver URL directly. Do not put passwords, access tokens, signing keys, or other secrets in this public JSON file. The brand option changes some app labels; it is not complete white-label rebranding.

3. Configure Nginx for the app

Create an Nginx server block such as /etc/nginx/sites-available/element. Replace the domain if needed. This simple configuration serves Element as static files and sends missing paths to index.html, while marking all responses for revalidation. That conservative cache policy avoids users receiving a stale app shell or stale config after a release; you can tune asset caching later if your deployment process preserves Element's required no-cache paths.

server {
    listen 80;
    listen [::]:80;
    server_name chat.example.com;

    root /var/www/element;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
        add_header Cache-Control "no-cache" always;
        add_header X-Frame-Options SAMEORIGIN always;
        add_header X-Content-Type-Options nosniff always;
        add_header Content-Security-Policy "frame-ancestors 'self'" always;
    }
}

Element's web hosting notes say not to cache /config.*.json, /i18n, /version, or /index.html, and recommend browser revalidation on page load. The example applies no-cache to everything as a straightforward starting point. It also includes security headers Element recommends, including a frame policy and MIME-sniffing protection. If you already define a Content Security Policy elsewhere, merge frame-ancestors 'self' into that policy instead of sending conflicting policies.

Enable the site and validate Nginx before reloading it:

sudo ln -s /etc/nginx/sites-available/element /etc/nginx/sites-enabled/element
sudo nginx -t
sudo systemctl reload nginx

4. Add HTTPS and test the client

Element should be served over HTTPS. Once DNS resolves to this server and port 80 is reachable, install Certbot using the current instructions for your distribution, then request and install a certificate with its Nginx integration. The Certbot project documents the certbot --nginx flow and renewal checks; package installation differs by operating system, so use its current Nginx instructions for your release. If Certbot edits the server block, run sudo nginx -t again and confirm that renewal is scheduled.

Open https://chat.example.com in a private browser window. The Element login screen should load without missing scripts or styles, show your expected homeserver, and have a valid lock icon in the browser address bar. Sign in with a test account and confirm that the browser can reach the homeserver. If login fails, inspect the browser developer console and network panel for blocked requests, certificate errors, or a wrong base_url.

Common deployment problems

  • A blank or half-loaded page: check that Nginx's root points to the directory containing index.html, and that the bundles and i18n directory were copied alongside it.
  • The wrong homeserver appears: validate the JSON syntax in config.json and confirm that the file is at the web root. If you configure a domain-specific config.chat.example.com.json, Element tries that file before config.json; the files are not merged.
  • Users see old settings after an update: ensure index.html, version, i18n, and configuration JSON are not cached. Clear or revalidate browser caches after changing the Nginx policy.
  • Login loads but API requests fail: check that the homeserver URL is correct, uses HTTPS, and is configured for browser access, including appropriate CORS behavior where required. Hosting Element on Nginx does not proxy or replace the Matrix homeserver.

For a successful deployment, the client loads at the custom domain over HTTPS, its configuration points to the intended homeserver, and a test account can sign in without failed network requests. Element's web hosting notes and the Nginx index documentation are the primary references for the static deployment and server-block behavior described here.

Leave a Comment

Host Element Web on Nginx with a Custom Homeserver

Deploy Element Web as a static site, point it to your Matrix homeserver, add HTTPS, and configure Nginx to serve updates without stale files.

Run a Lightweight Matrix Homeserver on Raspberry Pi 4

Set up Conduit on a 64-bit Raspberry Pi 4 with persistent data, HTTPS federation, protected registration, and checks for a working homeserver.

Set Up a Custom Matrix Room Alias on Your Own Domain

Give a Matrix room an easy-to-share address on your domain using Element or the Matrix API, with checks for permissions, Synapse naming, and federation.

Set Up coturn for Reliable Matrix Voice and Video Calls

Configure coturn and Synapse with matching TURN credentials, open the required relay ports, and verify that Matrix clients can obtain relay candidates.

Deploy Matrix Synapse with Docker Compose and PostgreSQL

Deploy Matrix Synapse with Docker Compose and PostgreSQL

Set up a persistent Synapse homeserver with Docker Compose, PostgreSQL, a private config, and checks before exposing it through HTTPS.

Customize Element Web’s Theme and Branding

Set a branded name, custom colors, and login assets for your Element Web deployment while understanding which parts remain Element-branded.

Raise Synapse’s Systemd File Limit Without Guesswork

Raise Synapse’s Systemd File Limit Without Guesswork

Diagnose whether Synapse hit its per-process open-file cap, set a systemd drop-in for the right service or worker, and verify the live limit.

Element Shows “Failed to Decrypt”? Restore the Missing Room Key

Element Shows “Failed to Decrypt”? Restore the Missing Room Key

Find out whether the error is limited to one browser or one event, then use Element’s recovery key or a trusted device without risking your remaining encrypted history.

Clean Up Old Synapse Messages and Media Without Losing Data

Use Synapse’s history and media purge APIs or retention settings to remove stale data safely, then verify completion and disk-space recovery.

Build a Matrix Echo Bot in Python with Simple-Matrix-Bot-Lib

Build a Matrix Echo Bot in Python with Simple-Matrix-Bot-Lib

Install the current library, connect a dedicated Matrix account, and run a small !echo bot with safer credential handling and a clear test.