Matrix is chat you run yourself, with end-to-end encryption, group rooms and voice and video calls. LibrePortal installs the Synapse server and the Element web app together, so you can start chatting from a browser straight away, and talk to the wider Matrix network later if you give it a domain.
On this page
- At a glance
- What it's good for
- Before you install: choose the server name
- Signing in
- Adding people
- Chatting on your phone and computer
- Talking to other Matrix servers
- Good to know
- What the install asks
- Addresses and ports
- Settings
- In its config file
- Tools
- Works with
- Privacy and security
- What leaves this server
- What LibrePortal turns off
- Sources
- Under the hood
Good to know before you install
Voice and video calls ask Google's STUN servers for the server's address unless you turn that off in Privacy settings; LiveKit hands Google's STUN to callers' apps unless LibreSTUN is installed.
At a glance#
- What it is
- Federated Chat Communication
- Where it opens
- Element Web Interface
On its own port at
http://your-server:port, orelement.your-domainonce you have a domain - Updates
- Automatic A backup is taken first, and it rolls back if the update fails
- Backups
- Included Part of the daily backup when that's switched on
- Copies
- As many as you like Run several copies, each with its own data
What it's good for#
Matrix is an open chat network, a bit like email for instant messages. Everyone has an address like @alice:example.com, and people on different servers can talk to each other in the same rooms. Running your own server means your conversations, files and contacts live on your hardware, and private chats are end-to-end encrypted so even the server can't read them.
LibrePortal runs two things for you: Synapse, the homeserver that holds the accounts and rooms, and Element, the web app you chat in. The app's Element Web Interface button opens Element, already pointed at your server.
Matrix, Mattermost, Rocket.Chat or Stoat?
All four are chat. Choose Matrix if you want encryption by default and the option to talk to people on other servers. Mattermost and Rocket.Chat are built for a team at work, with channels, threads and integrations, all on your one server. Stoat feels like Discord, with servers and voice channels, for a group of friends.
Before you install: choose the server name#
This is the one decision you can't change later, so it's worth a minute.
The server name is the part of every user ID after the colon: @alice: followed by the server name. Synapse signs it into every message it sends, so changing it later means starting again with a new database. The install asks for it when you have no domain set up in LibrePortal. What you get depends on your answer:
- With a domain in LibrePortal, it's
matrix.<your domain>, and people's IDs look like@alice:matrix.example.com. That's the kind of name that can talk to other Matrix servers. - With no domain, but a name typed in, it's that name. It doesn't need to point anywhere yet. You can chat over your home network today and connect to the rest of Matrix later, by pointing the name at your server and adding Traefik, without losing anything.
- With nothing at all, it's your server's network address, like
192.168.1.50. That's fine for a household chatting at home or over the LibrePortal VPN. It can never talk to other Matrix servers, though, and if the server's address ever changes, every user ID is left pointing at the old one.
If in doubt, type a domain you own
A domain costs nothing to put in the server name, even if you don't use it for months. An IP address in the server name is a dead end if you ever change your mind.
Signing in#
Sign-ups are switched off in LibrePortal's Matrix (CFG_MATRIX_ENABLE_REGISTRATION=false), so the way in is the admin account LibrePortal makes the moment Synapse is ready. It's called admin, and its password is in the Login Details shown when the install finishes. Press Welcome on the app's page to see them again.
In Element, sign in with just admin and the password. Element already knows which server it's on. Other apps may want the full ID, @admin: plus your server name.
The first start takes a little while, because Synapse sets up its database before it answers. LibrePortal waits for it, up to about two minutes, before making the account.
Don't switch sign-ups on before you install
If you turn registration on before installing, Matrix is open for sign-ups from its first start, before LibrePortal has made admin. Someone who reaches it in that minute or two could register the name admin themselves. Install with sign-ups off, and only open them later if you really need to.
Adding people#
Use the Tools tab rather than opening sign-ups, which on a public server invites spam accounts.
- Open Matrix's page in LibrePortal and go to Tools.
- Run Create User Account with a username, just the name part like
alice, not the full@alice:ID. Leave the password empty and one is made for you. Tick Make server admin only for people who should help run the server. - Send them the address of Element and their password, and ask them to change it once they're in.
The username is permanent: Matrix can't rename an account. The other tools do what they say: Reset User Password (which signs the person out of every device), Set Admin Status and List Users.
There's no delete in Matrix
Deactivate User Account is as far as it goes. It locks the account and clears the profile, but messages already sent stay in the rooms, and the username can never be used again on this server.
Chatting on your phone and computer#
Any Matrix app can sign in to your server. Element has apps for Android, iPhone, Windows, macOS and Linux, and there are others such as FluffyChat and Nheko. When an app asks for a homeserver, give it the address the Matrix Homeserver port answers on: https://matrix.example.com with a domain, or http://192.168.1.50: and the port number without one. The Config tab's Network section shows the port.
Desktop apps and Element in a browser are happy with plain http on your home network. Phone apps generally expect HTTPS, so if you want Matrix on your phone, a domain with HTTPS is the dependable way.
To check: check which current phone clients (Element X, Element classic, FluffyChat) sign in to LibrePortal's Synapse over plain http on a LAN address, and whether Element X works with it at all
Encrypted chats keep their keys on each device. When you sign in on a new one, Element asks you to verify it from a device you already have, or with your recovery key. Set up that recovery key the first time Element offers it; without it, a lost phone can mean old encrypted messages you can't read again.
Talking to other Matrix servers#
With a domain and Traefik, your server can join rooms on other servers and people elsewhere can message you. Synapse answers the "where is this server?" question itself on matrix.<your domain>, so there's nothing to set up on your main domain. The Matrix Homeserver port has to stay reachable from the internet for this, which is why it starts public.
If you'll only ever chat among yourselves, you can make both ports private and use the VPN when you're out.
Good to know#
- Don't put a login page in front of it. Matrix apps and other servers talk to Synapse directly and can't get past Authelia's sign-in or a password prompt, so leave both off for Matrix, even though the page below says it can sit behind Authelia.
- Uploads can be up to 50 MB each.
- Group video calls that Element starts with Jitsi go through Element's public Jitsi server,
meet.element.io, because that's what LibrePortal's Element is set up with. LibrePortal also has Jitsi Meet if you'd rather keep calls on your own server. - Updates are automatic within the Synapse version LibrePortal pins. A backup is taken first, and it includes the database and every uploaded file and avatar.
- Bridges to other chat networks are something Matrix can do, but LibrePortal doesn't install any.
What the install asks#
When you install Matrix, LibrePortal asks for a little more than usual before it starts:
- Server name. The end of every user ID. It can't be changed later. Empty uses this server's IP. You can leave this one empty.
- Extras. For chat and calls on phones. Both need a domain. Change them later under Tools.
Addresses and ports#
Matrix has 4 ports. LibrePortal picks a free port number for each when you install, so yours will differ from anyone else's. The Config tab's Network section shows them, and the app's Open button uses the right one. "Anyone" means it's reachable from wherever your server is reachable; you can make it private later.
| What it is | Who can reach it | With a domain |
|---|---|---|
| Matrix Homeserver (client + federation API) TCP | Anyone | matrix.your-domain |
| Element Web Interface | Anyone | element.your-domain |
| Calls (voice and video) UDP | Off until you turn it on | Port only |
| Calls (voice and video, TCP) TCP | Off until you turn it on | Port only |
Settings#
In its config file#
Matrix's own settings aren't on the Config tab yet. They live in the app's config file, described here so you know they exist. How to change them.
| Setting | What it does | Starts as |
|---|---|---|
ExtrasCFG_MATRIX_EXTRAS |
Optional parts of Matrix that are on; change them from the Tools tab | Empty |
NameCFG_MATRIX_DISPLAY_NAME |
What this app is called on your dashboards. Leave empty to use its usual name | Empty |
Show on the LibrePortal DashboardCFG_MATRIX_SHOW_ON_DASHBOARD |
Whether this app gets a shortcut on the front page of the LibrePortal WebUI, separate from any Dashy dashboard Choices: true, false |
true |
Usage StatisticsCFG_MATRIX_TELEMETRY |
Whether Synapse may send anonymous usage statistics to matrix.org Choices: true, false |
false |
Element Integration ManagerCFG_MATRIX_INTEGRATION_MANAGER |
Whether Element may use Element's own integration manager (scalar.vector.im) for bots, bridges and widgets Choices: true, false |
false |
Public STUN ServersCFG_MATRIX_PUBLIC_STUN |
Whether the calls server (LiveKit) may ask Google's STUN servers for its public address; off, it announces this server's public address from LibrePortal instead Choices: true, false |
true |
LibreSTUNCFG_MATRIX_LIBRESTUN |
Whether calls use this server's own STUN and TURN server (LibreSTUN) when it is installed; off keeps how this app made calls before Choices: auto, off |
auto |
Detailed logsCFG_MATRIX_VERBOSE_LOGS |
Whether Matrix writes its normal, chattier logs, including who connected, instead of only warnings and errors. Choices: true, false |
false |
Debug logging for 24 hoursCFG_MATRIX_DEBUG_LOGS |
Turn on to see everything Matrix is doing while you look for a problem; it turns itself off after 24 hours. Choices: true, false |
false |
Tools#
Matrix's Tools tab has 6 buttons for jobs you'd otherwise need a terminal for. Each one runs as a task, so you can watch it on the Tasks page and read what it did. More about Tools.
Phone notifications through ntfy, and voice and video calls. Removing one keeps every chat as it is.
Add a Matrix account. The username becomes permanent — @name:server can never be renamed.
Every account on this homeserver, including deactivated ones.
Set a new password and sign the user out of every device.
Grant or revoke Synapse server-admin rights.
Matrix has no delete. This revokes access and erases the profile, and the user ID stays permanently taken.
Works with#
These are the other apps Matrix knows how to work with. Once it's installed, its page shows the same list with whether each one is connected. How this works.
- Phone notifications (ntfy): Messages and calls reach Android phones through ntfy, without Google.
- Calls (LiveKit): Voice and video calls between phones, at home or away, through this server. There's nothing to switch on; LibrePortal shows whether it can work and lets you check.
- LibreSTUN: Calls connect from anywhere through your own STUN and TURN server, with nothing going to Google. LibrePortal sets this up by itself when both are installed.
- Grafana: Shows dashboards for the apps that have one. works with every app
- Home Assistant: Automations can message you on Matrix.
- Prometheus: Collects metrics from the apps that can export them. works with every app
- Uptime Kuma: Watches your apps and shows when one goes down. works with every app
Privacy and security#
Worth knowing Matrix keeps your chats on your server and sends no usage statistics. LibrePortal turns off Element's integration manager; group calls still use Element's public video service unless Jitsi Meet is installed here on a domain.
What leaves this server#
- Federation: messages reach the servers of the people you talk to
- Other servers' signing keys are fetched from matrix.org
- Group calls in Element use Element's public Jitsi server, unless Jitsi Meet is installed here on a domain
- Calls can use public STUN servers to find your address (switchable in Config); LibreSTUN gives callers your own
What LibrePortal turns off#
- Detailed logs and per-request access logging (switchable in Config)
- Element's integration manager (scalar.vector.im) (switchable in Config)
- Usage statistics (reporting is off) (switchable in Config)
Licence: AGPL-3.0 (Synapse, MAS, Element Web; Element also offers commercial terms); Apache-2.0 (LiveKit, lk-jwt-service). Audited: 21 October 2026. See the privacy of every app and the Promise.
Sources#
Under the hood#
- It runs these images:
matrixdotorg/synapse:v1.158.0@sha256:5f868df1f5772907c6dbe973a9b69ab530a5d6bb317c011a3788f7ad78eb1292,vectorim/element-web:v1.12.25@sha256:ac50d4eebafd954d7d7e2887d4693bcc91c54c0d00546a3410eeae77e6b342d5,ghcr.io/element-hq/matrix-authentication-service:1.26.0@sha256:e089f1048a1d4a9a492ed17b9fe759100f1bd619407b001f5927928d88b780c4,livekit/livekit-server:v1.13.9@sha256:d0c04791bf63ca8dcea123571827d56ba9504bd57c8d5de60ee03b5408cc3154,ghcr.io/element-hq/lk-jwt-service:0.9.0@sha256:d210fd778ba38b7e42e6fc64e8a24a7d66ccc3b938fb20d73bd713224af2dfea,postgres:15.19-alpine@sha256:54e0dd8e8cddcdbb9156c2486eed5a43eccb7214d7c6828097d41ce049fb3984. - It can sit behind Authelia's sign-in once Authelia is installed.
- Its own project and documentation: github.com/element-hq/synapse
Ports, settings, tools and connections on this page are read from LibrePortal v0.10.97's app catalogue each time the guide is built.
