Compare commits

...

16 Commits

Author SHA1 Message Date
Slavi Pantaleev
0b9389fd64
Update docs/configuring-playbook-livekit-server.md
Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com>
2024-11-23 17:43:52 +02:00
Slavi Pantaleev
9a8a569431
Update docs/configuring-playbook-element-call.md
Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com>
2024-11-23 17:43:29 +02:00
Slavi Pantaleev
bb403e1aee
Update docs/configuring-playbook-jwt-service.md
Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com>
2024-11-23 17:43:15 +02:00
Slavi Pantaleev
74fbacbd9f
Update docs/configuring-playbook-element-call.md
Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com>
2024-11-23 17:42:54 +02:00
Slavi Pantaleev
5642755273 Rework LiveKit JWT Service role 2024-11-23 16:40:50 +02:00
Slavi Pantaleev
bb925f4782 Merge branch 'master' into element-call-integration 2024-11-23 14:45:20 +02:00
Slavi Pantaleev
ca8c1cf2b5 Add support for Valkey and default to using it instead of KeyDB
Hopefully fixes https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3544
2024-11-23 14:43:04 +02:00
Suguru Hirahara
e36115a5b9
Add docs/just.md (#3811)
* Add docs/just.md as dedicated documentation of "just" commands

This is partially based on fb60ba67f646288b40818a555bb716405e144956 (announcement of adoption of "just" program). It also refers descriptions on installing.md.

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Create a table for examples

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Fix entries on the table

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Move the anchor link to "agru"

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Edit docs/faq.md: add an entry for the just

It is based on the existing explanation of the just on docs/maintenance-upgrading-services.md.

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Add links to docs/just.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/just.md: add a common note

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Clarify "What is just" section on FAQ

* Update just.md

* Mention install-service

---------

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Co-authored-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2024-11-23 11:52:48 +02:00
Suguru Hirahara
194a3ca461
Add "Quick start" guide (#3801)
* Add docs/quick-start.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Add description about keeping the playbook and services up-to-date

Also: move descriptions about difference between the playbook tags (setup-all and install-all) and about the just "recipe" from installing.md to maintenance-upgrading-services.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Replace <your-username> with YOUR_USERNAME_HERE

This is a common expression and should avoid misunderstanding that `<` and `>` would need to be included

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Replace <your-password> with YOUR_PASSWORD_HERE

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Change the link to 'Quick start' on the breadcrumbs from README.md to quick-start.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Add a link to quick-start.md on the "Getting started" section

Since I am not quite sure whether the link to prerequisites.md should be replaced in favor of this link, this commit leaves it as it is for now.

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Add a link to quick-start.md on docs/README.md

Since I am not quite sure whether the link to prerequisites.md should be replaced in favor of this link, this commit leaves it as it is for now.

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Add note about using "example.com" as an example domain

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Remove backticks from command examples to register a user

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Apply suggestions from code review

Co-authored-by: Slavi Pantaleev <slavi@devture.com>

* Improve notes for instruction to create a user account

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Add details about delegation to installing.md and quick-start.md

Some information is omitted on quick-start.md in favor of installing.md to keep the quick start guide simple.

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/quick-start.md: add the breadcrumb header

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Edit docs/quick-start.md: run the setup command with install-all by default

Refer docs/maintenance-upgrading-services.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Revert "Update docs/quick-start.md: add the breadcrumb header"

This reverts commit 9a6e1cf14c7638953fc8fbb8b487ea0afd0a41ad.

As the quick start guide is standalone.

* Update docs/quick-start.md: add headers inside the install section

These headers should make it perfectly clear that there are two steps to be done to install with the playbook

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update quick-start.md

* Update docs/registering-users.md: notes for manual user registeration

Copy the same notes from quick-start.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Reword some things in quick start

* Add alternative to `just roles`

* Update docs/configuring-dns.md: sync with docs/quick-start.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/quick-start.md: add a link to docs/registering-users.md for an instruction to add user accounts

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/registering-users.md and docs/updating-users-passwords.md: remove "your" from username and password placeholders

These documentations, unlike docs/installing.md and docs/quick-start.md, describe how to handle users (registering them or changing their passwords), some of whom are yours, while others are not.

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/installing.md: add "your" to make it clear that it is "your" account that is going to be created

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/installing.md and docs/quick-start.md: mention "make roles"

This commit adds mentions to "make roles" and a note about the preference of ansible-playbook commands over the just "recipes".

quick-start.md intends to be referred by those who have never used the playbook to set up a server, so it is safer to regard that it is not clear to them what exactly the just "recipes" are made of, ie. it takes some time and experience until someone understands simplicity of them. For beginners, I believe that we should prefer the basics over simplicity, from the educational point of view.

If someone feels tired of using the same command repetitively, then the person will have been already well accustomed to the way how the playbook works and how the server is supposed to be maintained, and the person is "qualified" to use the just "recipes", and should be able to use them with confidence, distinguishing the playbook tags from the "recipes", for example, from "just install-all" and "ansible-playbook -i inventory/hosts setup.yml --tags=install-all". Such level of familiarity and experience should not be expected on the quick start guide.

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update instructions to update Ansible roles

Also: move the detailed explanation about "just roles" from installing.md to maintenance-upgrading-services.md

TBD: create a dedicated documentation for the "just" program and the concept of its "recipe" (shortcut of commands)

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Add a note about cases to create multiple accounts/users

Since one of the quick start guide's goals is to set up an own user account, this commit adds the note about creating multiple accounts/users to installing.md and registering-users.md only. It should be fine as registering-users.md is linked from quick-start.md

Also:
- On installing.md and quick-start.md, change instruction from what encourages to select "admin=yes" or "admin=no" to what encourages to use "admin=yes", since your user account will be the sole user on the server, as long as you set up the server by following the documentation
- Remove the link to registering-users.md from quick-start.md as the documentation is already linked above, under the header of the section
- Sync docs/installing.md with other documentation

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Remove a line about setting "admin=yes" to reduce the amount of information

Because quick-start.md is getting longer with much information, it removes the note in favor of the linked registering-users.md documentation. The note is available on installing.md as well, and details about adding user accounts for other people can (and should) be checked on those documentations.

Also, this commit edits lines above these notes to make it clear that your user account will be an administrator of the server.

With this commit, the amount of the information about adding user accounts will be: registering-users.md > installing.md > quick-start.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Fix a broken anchor link on docs/installing.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Replace repetitive information about upgrading with an anchor link to docs/maintenance-upgrading-services.md

Because details to update/upgrade the Matrix services is not necessary for quick start and the amount of information should be reduced from the viewpoint of maintainability, this commit removes details to update/upgrade from quick-start.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/quick-start.md: add a note about keeping it tidy and simple

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/maintenance-checking-services.md and docs/quick-start.md: add instruction to use federation tester against the base domain

Per Slavi's suggestion.

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/installing.md and docs/quick-start.md: replace commands to finalize the installation

Per Slavi's suggestion.

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Clarify install-matrix-static-files to avoid confusion with install-all; Minor consistency improvements

---------

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Co-authored-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2024-11-23 09:59:29 +02:00
Slavi Pantaleev
7b6972aea5
Merge pull request #3810 from luixxiul/fix
Update docs/registering-users.md: fix broken anchor links
2024-11-23 07:21:12 +02:00
Suguru Hirahara
d617f4247c
Update docs/registering-users.md: fix broken anchor links
The anchor link has stopped working with 30c53cdea2055bf2ab6e7727a0a12295d9ba9eab.

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
2024-11-23 13:41:04 +09:00
Slavi Pantaleev
d48890c7a2
Merge pull request #3809 from luixxiul/fix
Replace the warning emoji in text style (U+26A0 FE0E) to emoji style (U+26A0 FE0F)
2024-11-22 21:22:28 +02:00
Suguru Hirahara
e8ae798423
Replace the warning emoji in text style (U+26A0 FE0E) to emoji style (U+26A0 FE0F)
This change makes it possible for terminals to render warning emoji in actual emoji (⚠️), not in text style (⚠).

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
2024-11-23 01:11:15 +09:00
Slavi Pantaleev
f1712cec73
Merge pull request #3806 from luixxiul/fix
Add .github/workflows/close-stale-issues.yml: close stale issues automatically
2024-11-22 08:29:30 +02:00
Suguru Hirahara
b8ed31527c
Add .github/workflows/close-stale-issues.yml: close stale issues automatically
With this commit, actions/stale on GitHub will add a label 'stale' on issues (on spantaleev/matrix-docker-ansible-deploy) after 60 days of inactivity and close the stale issues after 7 days of inactivity. Only issues with labels 'question' and/or 'needs-info' will be processed, and ones with a label 'confirmed' will not be processed automatically.

Please refer https://github.com/marketplace/actions/close-stale-issues

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
2024-11-22 13:57:29 +09:00
Slavi Pantaleev
c57d0d192d Eliminate remaining matrix references from LiveKit Server role 2024-11-21 19:45:07 +02:00
49 changed files with 889 additions and 429 deletions

View File

@ -0,0 +1,27 @@
---
name: 'Close stale issues'
on: # yamllint disable-line rule:truthy
schedule:
- cron: '30 1 * * *'
permissions:
issues: write
jobs:
stale:
if: github.repository == 'spantaleev/matrix-docker-ansible-deploy'
runs-on: ubuntu-latest
steps:
- uses: actions/stale@v9
with:
# Don't process pull requests at all
days-before-pr-stale: -1
stale-issue-message: 'This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 7 days.'
close-issue-message: 'This issue was closed because it has been stalled for 7 days with no activity. If this issue is still reproduced, feel free to provide the issue with up-to-date information.'
stale-issue-label: 'stale'
# Add this label to exempt the issue from being marked as stale due to inactivity
exempt-issue-labels: 'confirmed'
# An allow-list of label(s) to only process the issues which contain one of these label(s).
any-of-issue-labels: 'question,needs-info'
# Use this to do a dry run from a pull request
# debug-only: true

View File

@ -1,3 +1,45 @@
# 2024-11-23
## (Backward Compatibility Break) The playbook now defaults to Valkey, instead of KeyDB
**TLDR**: if the playbook installed KeyDB (or Redis) as a dependency for you before, it will now replace it with [Valkey](https://valkey.io/) (a drop-in alternative). We [previously switched from Redis to KeyDB](#backward-compatibility-break-the-playbook-now-defaults-to-keydb-instead-of-redis), but Valkey is a better alternative, so we're switching again.
The playbook used to install Redis or KeyDB if services have a need for a Redis-compatible implementation ([enabling worker support for Synapse](docs/configuring-playbook-synapse.md#load-balancing-with-workers), [enabling Hookshot encryption](docs/configuring-playbook-bridge-hookshot.md#end-to-bridge-encryption), etc.).
Earlier this year, we switched from Redis to KeyDB - see [(Backward Compatibility Break) The playbook now defaults to KeyDB, instead of Redis](#backward-compatibility-break-the-playbook-now-defaults-to-keydb-instead-of-redis).
Because Valkey seems to be a better successor to Redis (than KeyDB) and likely doesn't suffer from [issues like this one](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3544), we now replace KeyDB with Valkey.
Valkey (like KeyDB and Redis in the past) is an implicitly enabled dependency - you don't need custom configuration in `vars.yml` to enable it.
Next time your run the playbook (via the `setup-all` tag), **KeyDB will be automatically uninstalled and replaced with Valkey**. Some Synapse downtime may occur while the switch happens.
Users on `arm32` should be aware that there's **neither a prebuilt `arm32` container image for Valkey**, nor the Valkey role supports self-building yet. Users on this architecture likely don't run Synapse with workers, etc., so they're likely in no need of Valkey (or Redis/KeyDB). If Redis is necessary in an `arm32` deployment, disabling Valkey and making the playbook fall back to Redis is possible (see below).
**The playbook still supports Redis** and you can keep using Redis (for now) if you'd like, by adding this additional configuration to your `vars.yml` file:
```yml
# Explicitly disable both Valkey and KeyDB.
#
# Redis will be auto-enabled if necessary,
# because there's no other Redis-compatible implementation being enabled.
valkey_enabled: false
keydb_enabled: false
```
**The playbook still supports KeyDB** and you can keep using KeyDB (for now) if you'd like, by adding this additional configuration to your `vars.yml` file:
```yml
# Explicitly disable Valkey enable KeyDB.
#
# Redis will not be auto-enabled beandcause a Redis-compatible implementation (KeyDB) is enabled.
valkey_enabled: false
keydb_enabled: true
```
At some point in time in the future, we'll remove both KeyDB and Redis from the playbook, so we recommend that you migrate to Valkey earlier anyway.
# 2024-11-14 # 2024-11-14
## HTTP-compression support for Traefik-based setups ## HTTP-compression support for Traefik-based setups

View File

@ -27,6 +27,8 @@ While the [list of supported services](#-supported-services) and documentation i
- Starting with the basics. You can always add/remove or tweak services later on. - Starting with the basics. You can always add/remove or tweak services later on.
- Following our guided installation, starting with the [Prerequisites](./docs/prerequisites.md) documentation page - Following our guided installation, starting with the [Prerequisites](./docs/prerequisites.md) documentation page
If you have never configured Matrix services, follow the [**quick start**](./docs/quick-start.md) guide to set up minimum core services on your server.
## ✔ Supported services ## ✔ Supported services
Using this playbook, you can get the following list of services configured on your server. Basically, this playbook aims to get you up-and-running with all the necessities around Matrix, without you having to do anything else. Using this playbook, you can get the following list of services configured on your server. Basically, this playbook aims to get you up-and-running with all the necessities around Matrix, without you having to do anything else.

View File

@ -2,6 +2,8 @@
- [FAQ](faq.md) - lots of questions and answers. Jump to [Prerequisites](prerequisites.md) to avoid reading too much and to just start a guided installation. - [FAQ](faq.md) - lots of questions and answers. Jump to [Prerequisites](prerequisites.md) to avoid reading too much and to just start a guided installation.
- [Quick start](quick-start.md) - follow the guide to set up minimum core services on your server
- [Prerequisites](prerequisites.md) - go here to a guided installation using this Ansible playbook - [Prerequisites](prerequisites.md) - go here to a guided installation using this Ansible playbook
- [Configuring your DNS settings](configuring-dns.md) - [Configuring your DNS settings](configuring-dns.md)

View File

@ -1,6 +1,6 @@
# Configuring your DNS settings # Configuring your DNS settings
<sup>⚡️[Quick start](README.md) | [Prerequisites](prerequisites.md) > Configuring your DNS settings > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup> <sup>⚡️[Quick start](quick-start.md) | [Prerequisites](prerequisites.md) > Configuring your DNS settings > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>
To set up Matrix on your domain, you'd need to do some DNS configuration. To set up Matrix on your domain, you'd need to do some DNS configuration.
@ -36,7 +36,7 @@ The `element.example.com` subdomain is necessary, because this playbook installs
Be mindful as to how long it will take for the DNS records to propagate. Be mindful as to how long it will take for the DNS records to propagate.
If you are using Cloudflare DNS, make sure to disable the proxy and set all records to `DNS only`. Otherwise, fetching certificates will fail. If you are using Cloudflare DNS, make sure to disable the proxy and set all records to "DNS only". Otherwise, fetching certificates will fail.
## DNS settings for optional services/features ## DNS settings for optional services/features

View File

@ -25,16 +25,13 @@ Ensure that the following DNS names have a public IP/FQDN:
## Adjusting the playbook configuration ## Adjusting the playbook configuration
NOTE: Element call is dependent on two other services for it to function as intended. In orter to utilise Element Call you need to also enable the [JWT Service](configuring-playbook-jwt-service.md) and [Livekit Server](configuring-playbook-livekit-server.md). NOTE: Enabling Element Call will automatically enable the [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) and Livekit Server services.
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yaml ```yaml
matrix_element_call_enabled: true matrix_element_call_enabled: true
# Set a secure key for LiveKit authentication
livekit_server_config_keys_devkey: 'your-secure-livekit-key'
``` ```
## Installing ## Installing
@ -43,7 +40,7 @@ After configuring the playbook and potentially [adjusting your DNS records](#adj
## Usage ## Usage
Once installed, Element Call integrates seamlessly with Matrix clients like Element Web. When the Element Call service is installed, the `/.well-known/matrix/client` file is also updated. A new `org.matrix.msc4143.rtc_foci` section is added to point to your JWT service URL (e.g., `https://sfu-jwt.example.com`). Once installed, Element Call integrates seamlessly with Matrix clients like [Element Web](configuring-playbook-client-element-web.md). When the Element Call service is installed, the `/.well-known/matrix/client` file is also updated. A new `org.matrix.msc4143.rtc_foci` section is added to point to your LiveKit JWT service URL (e.g., `https://matrix.example.com/lk-jwt-service`).
Additionally, the `/.well-known/element/element.json` file is created to help Element clients discover the Element Call URL (e.g., `https://call.example.com`). Additionally, the `/.well-known/element/element.json` file is created to help Element clients discover the Element Call URL (e.g., `https://call.example.com`).
@ -53,12 +50,12 @@ To ensure the services function correctly, the following firewall rules and port
LiveKit: LiveKit:
• Forward UDP ports 50100:50200 to the Docker instance running LiveKit. - Forward UDP ports 50100:50120 to the Docker instance running LiveKit.
Forward TCP port 7881 to the Docker instance running LiveKit. - Forward TCP port 7881 to the Docker instance running LiveKit.
Element Call: Element Call:
Forward TCP port 443 to the server running Traefik (for Element Call). - Forward TCP port 443 to the server running Traefik (for Element Call).
Ensure these ports are open and forwarded appropriately to allow traffic to flow correctly between the services. Ensure these ports are open and forwarded appropriately to allow traffic to flow correctly between the services.

View File

@ -6,7 +6,7 @@ The email server would attempt to deliver emails directly to their final destina
By default, emails are sent from `matrix@matrix.example.com`, as specified by the `exim_relay_sender_address` playbook variable. By default, emails are sent from `matrix@matrix.example.com`, as specified by the `exim_relay_sender_address` playbook variable.
**Warning**: On some cloud providers (Google Cloud, etc.), [port 25 is always blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/), so sending email directly from your server is not possible. You will need to [relay email through another SMTP server](#relaying-email-through-another-smtp-server). **Warning**: On some cloud providers (Google Cloud, etc.), [port 25 is always blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/), so sending email directly from your server is not possible. You will need to [relay email through another SMTP server](#relaying-email-through-another-smtp-server).
💡 To improve deliverability, we recommend [relaying email through another SMTP server](#relaying-email-through-another-smtp-server) anyway. 💡 To improve deliverability, we recommend [relaying email through another SMTP server](#relaying-email-through-another-smtp-server) anyway.

View File

@ -1,6 +1,6 @@
# Setting up JWT Service (optional) # Setting up JWT Service (optional)
The playbook can install and configure [JWT Service](https://github.com/element-hq/lk-jwt-service) for you. The playbook can install and configure [LiveKit JWT Service](https://github.com/element-hq/lk-jwt-service) for you.
LK-JWT-Service is currently used for a single reason: generate JWT tokens with a given identity for a given room, so that users can use them to authenticate against LiveKit SFU. LK-JWT-Service is currently used for a single reason: generate JWT tokens with a given identity for a given room, so that users can use them to authenticate against LiveKit SFU.
@ -8,28 +8,23 @@ See the project's [documentation](https://github.com/element-hq/lk-jwt-service/)
## Decide on a domain and path ## Decide on a domain and path
By default, JWT Service is configured to be served on the Matrix domain (`sfu-jwt.DOMAIN`, controlled by the `matrix_jwt-service_hostname` variable). By default, JWT Service is configured to be served:
- on the Matrix domain (`matrix.example.com`), configurable via `matrix_livekit_jwt_service_hostname`
- under a `/lk-jwt-service` path prefix, configurable via `matrix_livekit_jwt_service_path_prefix`
This makes it easy to set it up, **without** having to adjust your DNS records manually. This makes it easy to set it up, **without** having to adjust your DNS records manually.
If you'd like to run JWT Service on another hostname or path, use the `matrix_jwt-service_hostname` variable.
## Adjusting DNS records ## Adjusting DNS records
If you've changed the default hostname, **you may need to adjust your DNS** records accordingly to point to the correct server. If you've changed the default hostname, **you may need to adjust your DNS** records accordingly to point to the correct server.
Ensure that the following DNS names have a public IP/FQDN:
- `sfu-jwt.DOMAIN`
## Adjusting the playbook configuration ## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml ```yaml
matrix_jwt_service_enabled: true matrix_livekit_jwt_service_enabled: true
# Set a secure key for LiveKit authentication
matrix_element_call_livekit_dev_key: 'your-secure-livekit-key'
``` ```
## Installing ## Installing
@ -38,8 +33,8 @@ After configuring the playbook and potentially [adjusting your DNS records](#adj
## Usage ## Usage
Once installed, a new `org.matrix.msc4143.rtc_foci` section is added to the element web client to point to your JWT service URL (e.g., `https://sfu-jwt.example.com`). Once installed, a new `org.matrix.msc4143.rtc_foci` section is added to the Element Web client to point to your JWT service URL (e.g., `https://matrix.example.com/lk-jwt-service`).
## Additional Information ## Additional Information
Refer to the JWT-Service documentation for more details on configuring and using JWT Service. Refer to the LiveKit JWT-Service documentation for more details on configuring and using JWT Service.

View File

@ -45,8 +45,8 @@ To ensure the services function correctly, the following firewall rules and port
LiveKit: LiveKit:
Forward UDP ports 50100:50200 to the Docker instance running LiveKit. - Forward UDP ports 50100:50200 to the Docker instance running LiveKit.
Forward TCP port 7881 to the Docker instance running LiveKit. - Forward TCP port 7881 to the Docker instance running LiveKit.
Ensure these ports are open and forwarded appropriately to allow traffic to flow correctly between the services. Ensure these ports are open and forwarded appropriately to allow traffic to flow correctly between the services.

View File

@ -36,9 +36,9 @@ Below, we'll try to **highlight some potential reasons for switching** to Matrix
## Prerequisites ## Prerequisites
- ⚠ the [Synapse](configuring-playbook-synapse.md) homeserver implementation (which is the default for this playbook). Other homeserver implementations ([Dendrite](./configuring-playbook-dendrite.md), [Conduit](./configuring-playbook-conduit.md), etc.) do not support integrating wtih Matrix Authentication Service yet. - ⚠ the [Synapse](configuring-playbook-synapse.md) homeserver implementation (which is the default for this playbook). Other homeserver implementations ([Dendrite](./configuring-playbook-dendrite.md), [Conduit](./configuring-playbook-conduit.md), etc.) do not support integrating wtih Matrix Authentication Service yet.
- ⚠ **email sending** configured (see [Adjusting email-sending settings](./configuring-playbook-email.md)), because **Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user** going through the new SSO-based login flow. It's also possible to [work around email deliverability issues](#working-around-email-deliverability-issues) if your email configuration is not working. - ⚠ **email sending** configured (see [Adjusting email-sending settings](./configuring-playbook-email.md)), because **Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user** going through the new SSO-based login flow. It's also possible to [work around email deliverability issues](#working-around-email-deliverability-issues) if your email configuration is not working.
- ❌ **disabling all password providers** for Synapse (things like [shared-secret-auth](./configuring-playbook-shared-secret-auth.md), [rest-auth](./configuring-playbook-rest-auth.md), [LDAP auth](./configuring-playbook-ldap-auth.md), etc.) More details about this are available in the [Expectations](#expectations) section below. - ❌ **disabling all password providers** for Synapse (things like [shared-secret-auth](./configuring-playbook-shared-secret-auth.md), [rest-auth](./configuring-playbook-rest-auth.md), [LDAP auth](./configuring-playbook-ldap-auth.md), etc.) More details about this are available in the [Expectations](#expectations) section below.
@ -62,17 +62,17 @@ This section details what you can expect when switching to the Matrix Authentica
- ❌ **Encrypted appservices** do not work yet (related to [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190) and [PR 17705 for Synapse](https://github.com/element-hq/synapse/pull/17705)), so all bridges/bots that rely on encryption will fail to start (see [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3658) for Hookshot). You can use these bridges/bots only if you **keep end-to-bridge encryption disabled** (which is the default setting). - ❌ **Encrypted appservices** do not work yet (related to [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190) and [PR 17705 for Synapse](https://github.com/element-hq/synapse/pull/17705)), so all bridges/bots that rely on encryption will fail to start (see [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3658) for Hookshot). You can use these bridges/bots only if you **keep end-to-bridge encryption disabled** (which is the default setting).
- ⚠ **You will need to have email sending configured** (see [Adjusting email-sending settings](./configuring-playbook-email.md)), because **Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user** going through the new SSO-based login flow. It's also possible to [work around email deliverability issues](#working-around-email-deliverability-issues) if your email configuration is not working. - ⚠ **You will need to have email sending configured** (see [Adjusting email-sending settings](./configuring-playbook-email.md)), because **Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user** going through the new SSO-based login flow. It's also possible to [work around email deliverability issues](#working-around-email-deliverability-issues) if your email configuration is not working.
- ⚠ [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) is **possible**, but requires **some playbook-assisted manual work**. Migration is **reversible with no or minor issues if done quickly enough**, but as users start logging in (creating new login sessions) via the new MAS setup, disabling MAS and reverting back to the Synapse user database will cause these new sessions to break. - ⚠ [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) is **possible**, but requires **some playbook-assisted manual work**. Migration is **reversible with no or minor issues if done quickly enough**, but as users start logging in (creating new login sessions) via the new MAS setup, disabling MAS and reverting back to the Synapse user database will cause these new sessions to break.
- ⚠ [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) does not currently seem to preserve the "admin" flag for users (as found in the Synapse database). All users are imported as non-admin - see [element-hq/matrix-authentication-service#3440](https://github.com/element-hq/matrix-authentication-service/issues/3440). You may need update the Matrix Authentication Service's database manually and adjust the `can_request_admin` column in the `users` table to `true` for users that need to be administrators (e.g. `UPDATE users SET can_request_admin = true WHERE username = 'someone';`) - ⚠ [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) does not currently seem to preserve the "admin" flag for users (as found in the Synapse database). All users are imported as non-admin - see [element-hq/matrix-authentication-service#3440](https://github.com/element-hq/matrix-authentication-service/issues/3440). You may need update the Matrix Authentication Service's database manually and adjust the `can_request_admin` column in the `users` table to `true` for users that need to be administrators (e.g. `UPDATE users SET can_request_admin = true WHERE username = 'someone';`)
- ⚠ Delegating user authentication to MAS causes **your Synapse server to be completely dependant on one more service** for its operations. MAS is quick & lightweight and should be stable enough already, but this is something to keep in mind when making the switch. - ⚠ Delegating user authentication to MAS causes **your Synapse server to be completely dependant on one more service** for its operations. MAS is quick & lightweight and should be stable enough already, but this is something to keep in mind when making the switch.
- ⚠ If you've got [OIDC configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on), you will need to migrate your OIDC configuration to MAS by adding an [Upstream OAuth2 configuration](#upstream-oauth2-configuration). - ⚠ If you've got [OIDC configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on), you will need to migrate your OIDC configuration to MAS by adding an [Upstream OAuth2 configuration](#upstream-oauth2-configuration).
- ⚠ A [compatibility layer](https://element-hq.github.io/matrix-authentication-service/setup/homeserver.html#set-up-the-compatibility-layer) is installed - all `/_matrix/client/*/login` (etc.) requests will be routed to MAS instead of going to the homeserver. This is done both publicly (e.g. `https://matrix.example.com/_matrix/client/*/login`) and on the internal Traefik entrypoint (e.g. `https://matrix-traefik:8008/_matrix/client/*/login`) which helps addon services reach the homeserver's Client-Server API. You typically don't need to do anything to make this work, but it's good to be aware of it, especially if you have a [custom webserver setup](./configuring-playbook-own-webserver.md). - ⚠ A [compatibility layer](https://element-hq.github.io/matrix-authentication-service/setup/homeserver.html#set-up-the-compatibility-layer) is installed - all `/_matrix/client/*/login` (etc.) requests will be routed to MAS instead of going to the homeserver. This is done both publicly (e.g. `https://matrix.example.com/_matrix/client/*/login`) and on the internal Traefik entrypoint (e.g. `https://matrix-traefik:8008/_matrix/client/*/login`) which helps addon services reach the homeserver's Client-Server API. You typically don't need to do anything to make this work, but it's good to be aware of it, especially if you have a [custom webserver setup](./configuring-playbook-own-webserver.md).
- ✅ Your **existing login sessions will continue to work** (you won't get logged out). Migration will require a bit of manual work and minutes of downtime, but it's not too bad. - ✅ Your **existing login sessions will continue to work** (you won't get logged out). Migration will require a bit of manual work and minutes of downtime, but it's not too bad.
@ -268,9 +268,9 @@ matrix_authentication_service_config_upstream_oauth2_providers:
💡 Refer to the [`upstream_oauth2.providers` setting](https://element-hq.github.io/matrix-authentication-service/reference/configuration.html#upstream_oauth2providers) for the most up-to-date schema and example for providers. The value shown above here may be out of date. 💡 Refer to the [`upstream_oauth2.providers` setting](https://element-hq.github.io/matrix-authentication-service/reference/configuration.html#upstream_oauth2providers) for the most up-to-date schema and example for providers. The value shown above here may be out of date.
⚠ The syntax for existing [OIDC providers configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on) is slightly different, so you will need to adjust your configuration when switching from Synapse OIDC to MAS upstream OAuth2. The syntax for existing [OIDC providers configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on) is slightly different, so you will need to adjust your configuration when switching from Synapse OIDC to MAS upstream OAuth2.
⚠ When [migrating an existing homeserver](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) which contains OIDC-sourced users, you will need to: When [migrating an existing homeserver](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) which contains OIDC-sourced users, you will need to:
- [Configure upstream OIDC provider mapping for syn2mas](#configuring-upstream-oidc-provider-mapping-for-syn2mas) - [Configure upstream OIDC provider mapping for syn2mas](#configuring-upstream-oidc-provider-mapping-for-syn2mas)
- go through the [migrating an existing homeserver](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) process - go through the [migrating an existing homeserver](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) process

View File

@ -22,7 +22,7 @@ matrix_synapse_admin_enabled: true
By default, synapse-admin installation will be [restricted to only work with one homeserver](https://github.com/etkecc/synapse-admin/blob/e21e44362c879ac41f47c580b04210842b6ff3d7/README.md#restricting-available-homeserver) - the one managed by the playbook. To adjust these restrictions, tweak the `matrix_synapse_admin_config_restrictBaseUrl` variable. By default, synapse-admin installation will be [restricted to only work with one homeserver](https://github.com/etkecc/synapse-admin/blob/e21e44362c879ac41f47c580b04210842b6ff3d7/README.md#restricting-available-homeserver) - the one managed by the playbook. To adjust these restrictions, tweak the `matrix_synapse_admin_config_restrictBaseUrl` variable.
**Warning**: If you're using [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) (MAS) for authentication, you will be able to [log into synapse-admin with an access token](https://github.com/etkecc/synapse-admin/pull/58), but certain synapse-admin features (especially those around user management) will be limited or not work at all. **Warning**: If you're using [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) (MAS) for authentication, you will be able to [log into synapse-admin with an access token](https://github.com/etkecc/synapse-admin/pull/58), but certain synapse-admin features (especially those around user management) will be limited or not work at all.
### Adjusting the Synapse Admin URL ### Adjusting the Synapse Admin URL

View File

@ -1,6 +1,6 @@
# Configuring the playbook # Configuring the playbook
<sup>⚡️[Quick start](README.md) | [Prerequisites](prerequisites.md) > [Configuring your DNS settings](configuring-dns.md) > [Getting the playbook](getting-the-playbook.md) > Configuring the playbook > [Installing](installing.md)</sup> <sup>⚡️[Quick start](quick-start.md) | [Prerequisites](prerequisites.md) > [Configuring your DNS settings](configuring-dns.md) > [Getting the playbook](getting-the-playbook.md) > Configuring the playbook > [Installing](installing.md)</sup>
If you've configured your DNS records and retrieved the playbook's source code to your computer, you can start configuring the playbook. To do so, follow these steps inside the playbook directory: If you've configured your DNS records and retrieved the playbook's source code to your computer, you can start configuring the playbook. To do so, follow these steps inside the playbook directory:
@ -214,7 +214,7 @@ Various services that don't fit any other categories.
- [Setting up the Element Call server](configuring-playbook-element-call.md) (optional) - [Setting up the Element Call server](configuring-playbook-element-call.md) (optional)
- [Setting up the JWT Service](configuring-playbook-jwt-service.md) (optional) - [Setting up the LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) (optional)
- [Setting up the Livekit server](configuring-playbook-livekit-server.md) (optional) - [Setting up the Livekit server](configuring-playbook-livekit-server.md) (optional)

View File

@ -80,6 +80,16 @@ Alternatively, you can download Ansible and the playbook itself directly on the
To learn more, see our [dedicated Ansible documentation page](ansible.md). To learn more, see our [dedicated Ansible documentation page](ansible.md).
### What is `just`?
[`just`](https://github.com/casey/just) is a modern command-runner alternative to [make](https://www.gnu.org/software/make/). It can be used to invoke commands with less typing.
The `just` utility executes shortcut commands (called "recipes"), which invoke `ansible-playbook`, `ansible-galaxy` or [`agru`](https://github.com/etkecc/agru) (depending on what is available in your system). The targets of the recipes are defined in [`justfile`](../justfile).
For details about `just` commands, take a look at: [Running `just` commands](just.md).
The playbook also contains a `Makefile` for the `make` tool, but most of the just recipes are not available as targets in the `Makefile`.
### Why use this playbook and not install Synapse and other things manually? ### Why use this playbook and not install Synapse and other things manually?
There are various guides telling you how easy it is to install [Synapse](https://github.com/element-hq/synapse). There are various guides telling you how easy it is to install [Synapse](https://github.com/element-hq/synapse).

View File

@ -1,6 +1,6 @@
# Getting the playbook # Getting the playbook
<sup>⚡️[Quick start](README.md) | [Prerequisites](prerequisites.md) > [Configuring your DNS settings](configuring-dns.md) > Getting the playbook > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup> <sup>⚡️[Quick start](quick-start.md) | [Prerequisites](prerequisites.md) > [Configuring your DNS settings](configuring-dns.md) > Getting the playbook > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>
This Ansible playbook is meant to be executed on your own computer (not the Matrix server). This Ansible playbook is meant to be executed on your own computer (not the Matrix server).

View File

@ -91,7 +91,7 @@ By default, Coturn is configured to wait on the certificate for the `matrix.` su
We also need to indicate to Coturn where the wildcard certificate is. We also need to indicate to Coturn where the wildcard certificate is.
**⚠ WARNING ⚠** : On first start of the services, Coturn might still fail to start because Traefik is still in the process of obtaining the certificates. If you still get an error, make sure Traefik obtained the certificates and restart the Coturn service (`just start-group coturn`). **⚠ WARNING ⚠** : On first start of the services, Coturn might still fail to start because Traefik is still in the process of obtaining the certificates. If you still get an error, make sure Traefik obtained the certificates and restart the Coturn service (`just start-group coturn`).
This should not happen again afterwards as Traefik will renew certificates well before their expiry date, and the Coturn service is setup to restart periodically. This should not happen again afterwards as Traefik will renew certificates well before their expiry date, and the Coturn service is setup to restart periodically.

View File

@ -1,16 +1,21 @@
# Installing # Installing
<sup>⚡️[Quick start](README.md) | [Prerequisites](prerequisites.md) > [Configuring your DNS settings](configuring-dns.md) > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > Installing</sup> <sup>⚡️[Quick start](quick-start.md) | [Prerequisites](prerequisites.md) > [Configuring your DNS settings](configuring-dns.md) > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > Installing</sup>
If you've configured your DNS records and the playbook, you can start the installation procedure. If you've configured your DNS records and the playbook, you can start the installation procedure.
## Update Ansible roles ## Update Ansible roles
Before installing, you need to update the Ansible roles in this playbook by running `just roles`. Before installing, you need to update the Ansible roles that this playbook uses and fetches from outside.
`just roles` is a shortcut (a `roles` target defined in [`justfile`](../justfile) and executed by the [`just`](https://github.com/casey/just) utility) which ultimately runs [agru](https://github.com/etkecc/agru) or [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) (depending on what is available in your system) to download Ansible roles. If you don't have `just`, you can also manually run the `roles` commands seen in the `justfile`. To update your playbook directory and all upstream Ansible roles (defined in the `requirements.yml` file), run:
There's another shortcut (`just update`) which updates the playbook (`git pull`) and updates roles (`just roles`) at the same time. - either: `just update`
- or: a combination of `git pull` and `just roles` (or `make roles` if you have `make` program on your computer instead of `just`)
If you don't have either `just` tool or `make` program, you can run the `ansible-galaxy` tool directly: `rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force`
For details about `just` commands, take a look at: [Running `just` commands](just.md).
## Install Matrix server and services ## Install Matrix server and services
@ -48,7 +53,7 @@ To do the installation **without** starting services, run `ansible-playbook` wit
ansible-playbook -i inventory/hosts setup.yml --tags=install-all ansible-playbook -i inventory/hosts setup.yml --tags=install-all
``` ```
**Note**: do not run the just "recipe" `just install-all` instead, because it automatically starts services at the end of execution. **Note**: do not run the just "recipe" `just install-all` instead, because it automatically starts services at the end of execution. See: [Difference between playbook tags and shortcuts](just.md#difference-between-playbook-tags-and-shortcuts)
When this command completes, services won't be running yet. When this command completes, services won't be running yet.
@ -74,18 +79,21 @@ As you have configured your brand new server and the client, you need to **creat
After creating the user account, you can log in to it with [Element Web](configuring-playbook-client-element-web.md) that this playbook has installed for you at this URL: `https://element.example.com/`. After creating the user account, you can log in to it with [Element Web](configuring-playbook-client-element-web.md) that this playbook has installed for you at this URL: `https://element.example.com/`.
To register a user via this Ansible playbook, run the command below on your local computer. To create your user account (as an administrator of the server) via this Ansible playbook, run the command below on your local computer.
**Notes**: **Notes**:
- Before running it, make sure to edit `YOUR_USERNAME_HERE` and `YOUR_PASSWORD_HERE` - Make sure to adjust `YOUR_USERNAME_HERE` and `YOUR_PASSWORD_HERE`
- In the command below, `YOUR_USERNAME_HERE` is just a plain username (like `john`), not your full `@user:example.com` identifier - For `YOUR_USERNAME_HERE`, use a plain username like `john`, not your full identifier (`@user:example.com`)
- Use `admin=yes` to make your user account an administrator of the Matrix server
```sh ```sh
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=YOUR_USERNAME_HERE password=YOUR_PASSWORD_HERE admin=<yes|no>' --tags=register-user ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=YOUR_USERNAME_HERE password=YOUR_PASSWORD_HERE admin=yes' --tags=register-user
# Example: `ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=john password=secret-password admin=yes' --tags=register-user` # Example: ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=john password=secret-password admin=yes' --tags=register-user
``` ```
Feel free to create as many accounts (for friends, family, etc.) as you want. Still, perhaps you should grant full administrative access to your account only (with `admin=yes`), and others should be created with `admin=no`.
For more information, see the documentation for [registering users](registering-users.md). For more information, see the documentation for [registering users](registering-users.md).
## Finalize the installation ## Finalize the installation
@ -94,20 +102,21 @@ Now you've configured Matrix services and your user account, you need to **final
This is required for federation to work! Without a proper configuration, your server will effectively not be part of the Matrix network. This is required for federation to work! Without a proper configuration, your server will effectively not be part of the Matrix network.
If you need the base domain for anything else such as hosting a website, you have to configure it manually, following the procedure described on the linked documentation. To configure the delegation, you have these two options. Choose one of them according to your situation.
However, if you do not need the base domain for anything else, the easiest way of configuring it is to [serve the base domain](configuring-playbook-base-domain-serving.md) from the integrated web server. It will enable you to use a Matrix user identifier like `@<username>:example.com` while hosting services on a subdomain like `matrix.example.com`. - If you can afford to point the base domain at the Matrix server, follow the instructions below which guide you into [serving the base domain](configuring-playbook-base-domain-serving.md) from the integrated web server. It will enable you to use a Matrix user identifier like `@<username>:example.com` while hosting services on a subdomain like `matrix.example.com`.
- Alternatively, if you're using the base domain for other purposes and cannot point it to the Matrix server (and thus cannot "serve the base domain" from it), you most likely need to [manually install well-known files on the base domain's server](configuring-well-known.md#manually-installing-well-known-files-on-the-base-domains-server), but feel free to familiarize yourself with all [server delegation (redirection) options](howto-server-delegation.md).
To configure server delegation in this way, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: To have the base domain served from the integrated web server, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml ```yaml
matrix_static_files_container_labels_base_domain_enabled: true matrix_static_files_container_labels_base_domain_enabled: true
``` ```
After configuring the playbook, run the installation command: After configuring the playbook, run the command below:
```sh ```sh
ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start ansible-playbook -i inventory/hosts setup.yml --tags=install-matrix-static-files,start
``` ```
## Things to do next ## Things to do next
@ -125,8 +134,12 @@ After finilizing the installation, you can:
### Maintaining your setup in the future ### Maintaining your setup in the future
Feel free to **re-run the setup command any time** you think something is off with the server configuration. Ansible will take your configuration and update your server to match. To update the playbook and the Ansible roles in the playbook, simply run `just roles`. While this playbook helps you to set up Matrix services and maintain them, it will **not** automatically run the maintenance task for you. You will need to update the playbook and re-run it **manually**.
Note that if you remove components from `vars.yml`, or if we switch some component from being installed by default to not being installed by default anymore, you'd need to run the setup command with `--tags=setup-all` instead of `--tags=install-all`. See [this page on the playbook tags](playbook-tags.md) for more information. The upstream projects, which this playbook makes use of, occasionally if not often suffer from security vulnerabilities.
A way to invoke these `ansible-playbook` commands with less typing in the future is to use [just](https://github.com/casey/just) to run the "recipe": `just install-all` or `just setup-all`. See [our `justfile`](../justfile) for more information. Since it is unsafe to keep outdated services running on the server connected to the internet, please consider to update the playbook and re-run it periodically, in order to keep the services up-to-date.
For more information about upgrading or maintaining services with the playbook, take at look at this page: [Upgrading the Matrix services](maintenance-upgrading-services.md)
Feel free to **re-run the setup command any time** you think something is off with the server configuration. Ansible will take your configuration and update your server to match.

38
docs/just.md Normal file
View File

@ -0,0 +1,38 @@
# Running `just` commands
We have previously used [make](https://www.gnu.org/software/make/) for easily running some playbook commands (e.g. `make roles` which triggers [`ansible-galaxy`](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html)). Our [`Makefile`](../Makefile) is still around, and you can still run these commands.
In addition, we have added support for running commands via [`just`](https://github.com/casey/just) - a more modern command-runner alternative to `make`. It can be used to invoke `ansible-playbook` commands with less typing.
The `just` utility executes shortcut commands (called as "recipes"), which invoke `ansible-playbook`, `ansible-galaxy` or [`agru`](https://github.com/etkecc/agru) (depending on what is available in your system). The targets of the recipes are defined in [`justfile`](../justfile). Most of the just recipes have no corresponding `Makefile` targets.
For some recipes such as `just update`, our `justfile` recommends installing [`agru`](https://github.com/etkecc/agru) (a faster alternative to `ansible-galaxy`) to speed up the process.
Here are some examples of shortcuts:
| Shortcut | Result |
|-----------------------------------------------|----------------------------------------------------------------------------------------------------------------|
| `just roles` | Install the necessary Ansible roles pinned in [`requirements.yml`](../requirements.yml) |
| `just update` | Run `git pull` (to update the playbook) and install the Ansible roles |
| `just install-all` | Run `ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-created,start` |
| `just setup-all` | Run `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start` |
| `just install-all --ask-vault-pass` | Run commands with additional arguments (`--ask-vault-pass` will be appended to the above installation command) |
| `just run-tags install-mautrix-slack,start` | Run specific playbook tags (here `install-mautrix-slack` and `start`) |
| `just install-service mautrix-slack` | Run `just run-tags install-mautrix-slack,start` with even less typing |
| `just start-all` | (Re-)starts all services |
| `just stop-group postgres` | Stop only the Postgres service |
| `just register-user john secret-password yes` | Registers a `john` user with the `secret-password` password and admin access (admin = `yes`) |
While [our documentation on prerequisites](prerequisites.md) lists `just` as one of the requirements for installation, using `just` is optional. If you find it difficult to install it, do not find it useful, or want to prefer raw `ansible-playbook` commands for some reason, feel free to run all commands manually. For example, you can run `ansible-galaxy` directly to install the Ansible roles: `rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force`.
## Difference between playbook tags and shortcuts
It is worth noting that `just` "recipes" are different from [playbook tags](playbook-tags.md). The recipes are shortcuts of commands defined in `justfile` and can be executed by the `just` program only, while the playbook tags are available for the raw `ansible-playbook` commands as well. Please be careful not to confuse them.
For example, these two commands are different:
- `just install-all`
- `ansible-playbook -i inventory/hosts setup.yml --tags=install-all`
The just recipe runs `ensure-matrix-users-created` and `start` tags after `install-all`, while the latter runs only `install-all` tag. The correct shortcut of the latter is `just run-tags install-all`.
Such kind of difference sometimes matters. For example, when you install a Matrix server into which you will import old data (see [here](installing.md#installing-a-server-into-which-youll-import-old-data)), you are not supposed to run `just install-all` or `just setup-all`, because these commands start services immediately after installing components which may prevent your from importing old data.

View File

@ -10,4 +10,4 @@ ansible-playbook -i inventory/hosts setup.yml --tags=self-check
If it's all green, everything is probably running correctly. If it's all green, everything is probably running correctly.
Besides this self-check, you can also check your server using the [Federation Tester](https://federationtester.matrix.org/). Besides this self-check, you can also check whether your server federates with the Matrix network by using the [Federation Tester](https://federationtester.matrix.org/) against your base domain (`example.com`), not the `matrix.example.com` subdomain.

View File

@ -65,7 +65,7 @@ docker run --rm --publish 1799:8080 --link matrix-postgres --net matrix adminer
You should then be able to browse the adminer database administration GUI at http://localhost:1799/ after entering your DB credentials (found in the `host_vars` or on the server in `{{matrix_synapse_config_dir_path}}/homeserver.yaml` under `database.args`) You should then be able to browse the adminer database administration GUI at http://localhost:1799/ after entering your DB credentials (found in the `host_vars` or on the server in `{{matrix_synapse_config_dir_path}}/homeserver.yaml` under `database.args`)
⚠️ Be **very careful** with this, there is **no undo** for impromptu DB operations. ⚠️ Be **very careful** with this, there is **no undo** for impromptu DB operations.
## Make Synapse faster ## Make Synapse faster

View File

@ -2,17 +2,39 @@
This playbook not only installs the various Matrix services for you, but can also upgrade them as new versions are made available. This playbook not only installs the various Matrix services for you, but can also upgrade them as new versions are made available.
While this playbook helps you to set up Matrix services and maintain them, it will **not** automatically run the maintenance task for you. You will need to update the playbook and re-run it **manually**.
The upstream projects, which this playbook makes use of, occasionally if not often suffer from security vulnerabilities (for example, see [here](https://github.com/element-hq/element-web/security) for known ones on Element Web).
Since it is unsafe to keep outdated services running on the server connected to the internet, please consider to update the playbook and re-run it periodically, in order to keep the services up-to-date.
The developers of this playbook strive to maintain the playbook updated, so that you can re-run the playbook to address such vulnerabilities. It is **your responsibility** to keep your server and the services on it up-to-date.
If you want to be notified when new versions of Synapse are released, you should join the Synapse Homeowners room: [#homeowners:matrix.org](https://matrix.to/#/#homeowners:matrix.org). If you want to be notified when new versions of Synapse are released, you should join the Synapse Homeowners room: [#homeowners:matrix.org](https://matrix.to/#/#homeowners:matrix.org).
To upgrade services: ## Steps to upgrade the Matrix services
Before updating the playbook and the Ansible roles in the playbook, take a look at [the changelog](../CHANGELOG.md) to see if there have been any backward-incompatible changes that you need to take care of.
If it looks good to you, go to the `matrix-docker-ansible-deploy` directory, then:
- update your playbook directory and all upstream Ansible roles (defined in the `requirements.yml` file) using: - update your playbook directory and all upstream Ansible roles (defined in the `requirements.yml` file) using:
- either: `just update` - either: `just update`
- or: a combination of `git pull` and `just roles` (or `make roles`) - or: a combination of `git pull` and `just roles` (or `make roles` if you have `make` program on your computer instead of `just`)
- take a look at [the changelog](../CHANGELOG.md) to see if there have been any backward-incompatible changes that you need to take care of If you don't have either `just` tool or `make` program, you can run the `ansible-galaxy` tool directly: `rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force`
- re-run the [playbook setup](installing.md) and restart all services: `just install-all` or `just setup-all` For details about `just` commands, take a look at: [Running `just` commands](just.md).
- re-run the [playbook setup](installing.md#maintaining-your-setup-in-the-future) and restart all services:
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start
```
Note that if you remove components from `vars.yml`, or if we switch some component from being installed by default to not being installed by default anymore, you'd need to run the setup command with `--tags=setup-all` instead of `--tags=install-all`. See [this page on the playbook tags](playbook-tags.md) for more information.
A way to invoke these `ansible-playbook` commands with less typing is to run the `just` "recipe": `just install-all` or `just setup-all`.
**Note**: major version upgrades to the internal PostgreSQL database are not done automatically. To upgrade it, refer to the [upgrading PostgreSQL guide](maintenance-postgres.md#upgrading-postgresql). **Note**: major version upgrades to the internal PostgreSQL database are not done automatically. To upgrade it, refer to the [upgrading PostgreSQL guide](maintenance-postgres.md#upgrading-postgresql).

View File

@ -20,4 +20,6 @@ Here are some playbook tags that you should be familiar with:
- `ensure-matrix-users-created` - a special tag which ensures that all special users needed by the playbook (for bots, etc.) are created - `ensure-matrix-users-created` - a special tag which ensures that all special users needed by the playbook (for bots, etc.) are created
`setup-*` tags and `install-*` tags **do not start services** automatically, because you may wish to do things before starting services, such as importing a database dump, restoring data from another server, etc. **Notes**:
- `setup-*` tags and `install-*` tags **do not start services** automatically, because you may wish to do things before starting services, such as importing a database dump, restoring data from another server, etc.
- Please be careful not to confuse the playbook tags with the `just` shortcut commands ("recipes"). For details about `just` commands, see: [Running `just` commands](just.md)

View File

@ -1,9 +1,11 @@
# Prerequisites # Prerequisites
<sup>⚡️[Quick start](README.md) | Prerequisites > [Configuring your DNS settings](configuring-dns.md) > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup> <sup>⚡️[Quick start](quick-start.md) | Prerequisites > [Configuring your DNS settings](configuring-dns.md) > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>
To install Matrix services using this Ansible playbook, you need to prepare several requirements both on your local computer (where you will run the playbook to configure the server) and the server (where the playbook will install the Matrix services for you). **These requirements need to be set up manually** before proceeding to the next step. To install Matrix services using this Ansible playbook, you need to prepare several requirements both on your local computer (where you will run the playbook to configure the server) and the server (where the playbook will install the Matrix services for you). **These requirements need to be set up manually** before proceeding to the next step.
We will be using `example.com` as the domain in the following instruction. Please remember to replace it with your own domain before running any commands.
## Your local computer ## Your local computer
- [Ansible](http://ansible.com/) program. It's used to run this playbook and configures your server for you. Take a look at [our guide about Ansible](ansible.md) for more information, as well as [version requirements](ansible.md#supported-ansible-versions) and alternative ways to run Ansible. - [Ansible](http://ansible.com/) program. It's used to run this playbook and configures your server for you. Take a look at [our guide about Ansible](ansible.md) for more information, as well as [version requirements](ansible.md#supported-ansible-versions) and alternative ways to run Ansible.
@ -12,7 +14,7 @@ To install Matrix services using this Ansible playbook, you need to prepare seve
- [`git`](https://git-scm.com/) as the recommended way to download the playbook. `git` may also be required on the server if you will be [self-building](self-building.md) components. - [`git`](https://git-scm.com/) as the recommended way to download the playbook. `git` may also be required on the server if you will be [self-building](self-building.md) components.
- [`just`](https://github.com/casey/just) for running `just roles`, `just update`, etc. (see [`justfile`](../justfile)), although you can also run these commands manually - [`just`](https://github.com/casey/just) for running `just roles`, `just update`, etc. (see [`justfile`](../justfile)), although you can also run these commands manually. Take at look at this documentation for more information: [Running `just` commands](just.md).
- Strong password (random strings) generator. The playbook often requires you to create a strong password and use it for settings on `vars.yml`, components, etc. As any tools should be fine, this playbook has adopted [`pwgen`](https://linux.die.net/man/1/pwgen) (running `pwgen -s 64 1`). [Password Tech](https://pwgen-win.sourceforge.io/), formerly known as "PWGen for Windows", is available as free and open source password generator for Windows. Generally, using a random generator available on the internet is not recommended. - Strong password (random strings) generator. The playbook often requires you to create a strong password and use it for settings on `vars.yml`, components, etc. As any tools should be fine, this playbook has adopted [`pwgen`](https://linux.die.net/man/1/pwgen) (running `pwgen -s 64 1`). [Password Tech](https://pwgen-win.sourceforge.io/), formerly known as "PWGen for Windows", is available as free and open source password generator for Windows. Generally, using a random generator available on the internet is not recommended.

202
docs/quick-start.md Normal file
View File

@ -0,0 +1,202 @@
# Quick start
<!--
NOTE:
- Let's keep it as tidy and simple as possible.
- Because this documentation is intended to be referred by those who have not configured a Matrix server and services by using the playbook, from the educational point of view it intentionally avoids instructions based on just program's "recipes" in favor of ansible-playbook commands in most cases.
-->
This page explains how to use this Ansible playbook to install Matrix services on your server with a minimal set of core services.
We will be using `example.com` as the "base domain" in the following instruction.
By following the instruction on this page, you will set up:
- **your own Matrix server** on a `matrix.example.com` server, which is configured to present itself as `example.com`
- **your user account** like `@user:example.com` on the server
- a **self-hosted Matrix client**, [Element Web](configuring-playbook-client-element-web.md) with the default subdomain at `element.example.com`
- Matrix delegation, so that your `matrix.example.com` server (presenting itself as `example.com`) can join the Matrix Federation and communicate with any other server in the Matrix network
Please remember to replace `example.com` with your own domain before running any commands.
## Prerequisites
<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Prerequisites](prerequisites.md)</sup>
At first, **check prerequisites** and prepare for installation by setting up programs [on your own computer](prerequisites.md#your-local-computer) and [your server](prerequisites.md#server). You also need `root` access on your server (a user that could elevate to `root` via `sudo` also works).
<!--
TODO: Add one liners (or instructions, a script, etc.) for easy and consistent installation of required software. See: https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3757
-->
If you encounter an error during installation, please make sure that you have installed and configured programs correctly.
One of the main reasons of basic errors is using an incompatible version of required software such as Ansible. Take a look at [our guide about Ansible](ansible.md) for more information. In short: installing the latest available version is recommended.
## Configure your DNS settings
<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Configuring your DNS settings](configuring-dns.md)</sup>
After installing and configuring prerequisites, you will need to **configure DNS records**.
To configure Matrix services in the default settings, go to your DNS service provider, and adjust DNS records as below.
| Type | Host | Priority | Weight | Port | Target |
| ----- | ---------------------------- | -------- | ------ | ---- | ---------------------|
| A | `matrix` | - | - | - | `matrix-server-IP` |
| CNAME | `element` | - | - | - | `matrix.example.com` |
As the table illustrates, you need to create 2 subdomains (`matrix.example.com` and `element.example.com`) and point both of them to your server's IP address (DNS `A` record or `CNAME` record is fine).
It might take some time for the DNS records to propagate after creation.
**💡 Note**: if you are using Cloudflare DNS, make sure to disable the proxy and set all records to "DNS only"
## Get the playbook
<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Getting the playbook](getting-the-playbook.md)</sup>
Next, let's **get the playbook's source code**.
We recommend to do so with [git](https://git-scm.com/) as it enables you to keep it up to date with the latest source code. While it is possible to download the playbook as a ZIP archive, it is not recommended.
To get the playbook with git, install git on your computer, go to a directory, and run the command:
```sh
git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git
```
It will fetch the playbook to a new `matrix-docker-ansible-deploy` directory underneath the directory you are currently in.
## Configure the playbook
<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Configuring the playbook](configuring-playbook.md)</sup>
Now that the playbook was fetched, it is time to **configure** it per your needs.
To install Matrix services with this playbook, you would at least need 2 configuration files.
For your convenience, we have prepared example files of them ([`vars.yml`](../examples/vars.yml) and [`hosts`](../examples/hosts)).
To start quickly based on these example files, go into the `matrix-docker-ansible-deploy` directory and follow the instructions below:
1. Create a directory to hold your configuration: `mkdir -p inventory/host_vars/matrix.example.com` where `example.com` is your "base domain"
2. Copy the sample configuration file: `cp examples/vars.yml inventory/host_vars/matrix.example.com/vars.yml`
3. Copy the sample inventory hosts file: `cp examples/hosts inventory/hosts`
4. Edit the configuration file (`inventory/host_vars/matrix.example.com/vars.yml`)
5. Edit the inventory hosts file (`inventory/hosts`)
Before editing these 2 files, make sure to read explanations on them to understand what needs to be configured.
**💡 Notes:**
- If you are not in control of anything on the base domain, you would need to set additional configuration on `vars.yml`. For more information, see [How do I install on matrix.example.com without involving the base domain?](faq.md#how-do-i-install-on-matrix-example-com-without-involving-the-base-domain) on our FAQ.
- Certain configuration decisions (like the base domain configured in `matrix_domain` and homeserver implementation configured in `matrix_homeserver_implementation`) are final. If you make the wrong choice and wish to change it, you'll have to run the Uninstalling step and start over.
- Instead of configuring a lot of things all at once, we recommend starting with the basic (default) settings in order to get yourself familiar with how the playbook works. After making sure that everything works as expected, you can add (and remove) advanced settings / features and run the playbook as many times as you wish.
## Install
<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Installing](installing.md)</sup>
After editing `vars.yml` and `hosts` files, let's start the **installation** procedure.
### Update Ansible roles
Before installing, you need to update the Ansible roles that this playbook uses and fetches from outside.
To update your playbook directory and all upstream Ansible roles, run:
- either: `just update`
- or: a combination of `git pull` and `just roles` (or `make roles` if you have `make` program on your computer instead of `just`)
If you don't have either `just` tool or `make` program, you can run the `ansible-galaxy` tool directly: `rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force`
### Run installation command
Then, run the command below to start installation:
````sh
ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-created,start
````
If you **don't** use SSH keys for authentication, but rather a regular password, you may need to add `--ask-pass` to the command.
If you **do** use SSH keys for authentication, **and** use a non-root user to *become* root (sudo), you may need to add `-K` (`--ask-become-pass`) to the command.
Wait until the command completes. If it's all green, everything should be running properly.
## Create your user account
<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Registering users](registering-users.md)</sup>
As you have configured your brand new server and the client, you need to **create your user account** on your Matrix server.
To create your user account (as an administrator of the server) via this Ansible playbook, run the command below on your local computer.
**💡 Notes**:
- Make sure to adjust `YOUR_USERNAME_HERE` and `YOUR_PASSWORD_HERE`
- For `YOUR_USERNAME_HERE`, use a plain username like `john`, not your full identifier (`@user:example.com`)
```sh
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=YOUR_USERNAME_HERE password=YOUR_PASSWORD_HERE admin=yes' --tags=register-user
# Example: ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=john password=secret-password admin=yes' --tags=register-user
```
<!--
NOTE: detailed instruction to add users can be found on docs/registering-users.md and installing.md, which include a note about usage of admin=yes and admin=no variables. In order to keep this guide as reasonably short as possible, let's not repeat the same instruction here.
-->
## Finalize server installation
<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Server Delegation](howto-server-delegation.md)</sup>
Now that you've configured Matrix services and your user account, you need to **finalize the installation process** by [setting up Matrix delegation (redirection)](howto-server-delegation.md), so that your Matrix server (`matrix.example.com`) can present itself as the base domain (`example.com`) in the Matrix network.
**This is required for federation to work!** Without a proper configuration, your server will effectively not be part of the Matrix network.
To configure the delegation, you have these two options. Choose one of them according to your situation.
- If you can afford to point the base domain at the Matrix server, follow the instruction below which guides you into [serving the base domain](configuring-playbook-base-domain-serving.md) from the integrated web server.
- Alternatively, if you're using the base domain for other purposes and cannot point it to the Matrix server (and thus cannot "serve the base domain" from it), you most likely need to [manually install well-known files on the base domain's server](configuring-well-known.md#manually-installing-well-known-files-on-the-base-domains-server).
To have the base domain served from the integrated web server, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_static_files_container_labels_base_domain_enabled: true
```
After configuring the playbook, run the command below and wait until it finishes:
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=install-matrix-static-files,start
```
💡 Running the `install-matrix-static-files` playbook tag (as done here) is an optimized version of running [the full setup command](#run-the-installation-command).
After the command finishes, you can also check whether your server federates with the Matrix network by using the [Federation Tester](https://federationtester.matrix.org/) against your base domain (`example.com`), not the `matrix.example.com` subdomain.
If you think something is off with the server configuration, feel free to [re-run the full setup command](#run-the-installation-command) any time.
## Log in to your user account
Finally, let's make sure that you can log in to the created account with the specified password.
You should be able to log in to it with your own [Element Web](configuring-playbook-client-element-web.md) client which you have set up at `element.example.com` by running the playbook. Open the URL (`https://element.example.com`) in a web browser and enter your credentials to log in.
**If you successfully logged in to your account, installing and configuring is complete**🎉
Come say Hi👋 in our support room - [#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com). You might learn something or get to help someone else new to Matrix hosting.
## Things to do next
Once you get familiar with the playbook, you might probably want to set up additional services such as a bridge on your server.
As this page intends to be a quick start guide which explains how to start the core Matrix services, it does not cover a topic like how to set them up. Take a look at the list of [things to do next](installing.md#things-to-do-next) to learn more.
### ⚠Keep the playbook and services up-to-date
While this playbook helps you to set up Matrix services and maintain them, it will **not** automatically run the maintenance task for you. You will need to update the playbook and re-run it **manually**.
Since it is unsafe to keep outdated services running on the server connected to the internet, please consider to update the playbook and re-run it periodically, in order to keep the services up-to-date.
For more information about upgrading or maintaining services with the playbook, take at look at this page: [Upgrading the Matrix services](maintenance-upgrading-services.md)

View File

@ -1,6 +1,6 @@
# Registering users # Registering users
This documentation page tells you how to create user account on your Matrix server. This documentation page tells you how to create user accounts on your Matrix server.
Table of contents: Table of contents:
@ -14,7 +14,10 @@ Table of contents:
## Registering users manually ## Registering users manually
**Note**: in the commands below, `<your-username>` is just a plain username (like `john`), not your full `@<username>:example.com` identifier. **Notes**:
- Make sure to adjust `USERNAME_HERE` and `PASSWORD_HERE`
- For `USERNAME_HERE`, use a plain username like `john`, not a full identifier (`@user:example.com`)
- Use `admin=yes` or `admin=no` depending on whether you wish to make the user an administrator of the Matrix server
After registering a user (using one of the methods below), **you can log in with that user** via the [Element Web](configuring-playbook-client-element-web.md) service that this playbook has installed for you at a URL like this: `https://element.example.com/`. After registering a user (using one of the methods below), **you can log in with that user** via the [Element Web](configuring-playbook-client-element-web.md) service that this playbook has installed for you at a URL like this: `https://element.example.com/`.
@ -22,10 +25,10 @@ After registering a user (using one of the methods below), **you can log in with
It's best to register users via the Ansible playbook, because it works regardless of homeserver implementation (Synapse, Dendrite, etc) or usage of [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md) (MAS). It's best to register users via the Ansible playbook, because it works regardless of homeserver implementation (Synapse, Dendrite, etc) or usage of [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md) (MAS).
To register a user via this Ansible playbook (make sure to edit the `<your-username>` and `<your-password>` part below): To register a user via this Ansible playbook:
```sh ```sh
just register-user <your-username> <your-password> <admin access: yes or no> just register-user USERNAME_HERE PASSWORD_HERE <admin access: yes or no>
# Example: `just register-user john secret-password yes` # Example: `just register-user john secret-password yes`
``` ```
@ -33,39 +36,41 @@ just register-user <your-username> <your-password> <admin access: yes or no>
**or** by invoking `ansible-playbook` manually: **or** by invoking `ansible-playbook` manually:
```sh ```sh
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-username> password=<your-password> admin=<yes|no>' --tags=register-user ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=USERNAME_HERE password=PASSWORD_HERE admin=<yes|no>' --tags=register-user
# Example: `ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=john password=secret-password admin=yes' --tags=register-user` # Example: ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=john password=secret-password admin=yes' --tags=register-user
``` ```
**Warning**: If you're registering users against Matrix Authentication Service, do note that it [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user. Upon a user's first login, they will be asked to confirm their email address. This requires that email sending is [configured](./configuring-playbook-email.md). You can also consult the [Working around email deliverability issues](./configuring-playbook-matrix-authentication-service.md#working-around-email-deliverability-issues) section for more information. Feel free to register as many users (for friends, family, etc.) as you want. Still, perhaps you should grant full administrative access to your user account only (with `admin=yes`), and others should be created with `admin=no`.
⚠️ **Warning**: If you're registering users against Matrix Authentication Service, do note that it [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user. Upon a user's first login, they will be asked to confirm their email address. This requires that email sending is [configured](./configuring-playbook-email.md). You can also consult the [Working around email deliverability issues](./configuring-playbook-matrix-authentication-service.md#working-around-email-deliverability-issues) section for more information.
### Registering users manually for Synapse ### Registering users manually for Synapse
If you're using the [Synapse](configuring-playbook-synapse.md) homeserver implementation (which is the default), you can register users via the command-line after **SSH**-ing to your server (requires that [all services have been started](#starting-the-services)): If you're using the [Synapse](configuring-playbook-synapse.md) homeserver implementation (which is the default), you can register users via the command-line after **SSH**-ing to your server (requires that [all services have been started](installing.md#install-matrix-server-and-services)):
```sh ```sh
/matrix/synapse/bin/register-user <your-username> <your-password> <admin access: 0 or 1> /matrix/synapse/bin/register-user USERNAME_HERE PASSWORD_HERE <admin access: 0 or 1>
# Example: `/matrix/synapse/bin/register-user john secret-password 1` # Example: `/matrix/synapse/bin/register-user john secret-password 1`
``` ```
### Registering users manually for Dendrite ### Registering users manually for Dendrite
If you're using the [Dendrite](./configuring-playbook-dendrite.md) homeserver implementation, you can register users via the command-line after **SSH**-ing to your server (requires that [all services have been started](#starting-the-services)): If you're using the [Dendrite](./configuring-playbook-dendrite.md) homeserver implementation, you can register users via the command-line after **SSH**-ing to your server (requires that [all services have been started](installing.md#install-matrix-server-and-services)):
```sh ```sh
/matrix/dendrite/bin/create-account <your-username> <your-password> <admin access: 0 or 1> /matrix/dendrite/bin/create-account USERNAME_HERE PASSWORD_HERE <admin access: 0 or 1>
# Example: `/matrix/dendrite/bin/create-account john secret-password 1` # Example: `/matrix/dendrite/bin/create-account john secret-password 1`
``` ```
### Registering users manually for Matrix Authentication Service ### Registering users manually for Matrix Authentication Service
If you're using the [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) and your existing homeserver (most likely [Synapse](./configuring-playbook-synapse.md)) is delegating authentication to it, you can register users via the command-line after **SSH**-ing to your server (requires that [all services have been started](#starting-the-services)): If you're using the [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) and your existing homeserver (most likely [Synapse](./configuring-playbook-synapse.md)) is delegating authentication to it, you can register users via the command-line after **SSH**-ing to your server (requires that [all services have been started](installing.md#install-matrix-server-and-services)):
```sh ```sh
/matrix/matrix-authentication-service/bin/register-user <your-username> <your-password> <admin access: 0 or 1> /matrix/matrix-authentication-service/bin/register-user USERNAME_HERE PASSWORD_HERE <admin access: 0 or 1>
# Example: `/matrix/matrix-authentication-service/bin/register-user john secret-password 1` # Example: `/matrix/matrix-authentication-service/bin/register-user john secret-password 1`
``` ```
@ -76,14 +81,14 @@ This `register-user` script actually invokes the `mas-cli manage register-user`
/matrix/matrix-authentication-service/bin/mas-cli manage register-user --help /matrix/matrix-authentication-service/bin/mas-cli manage register-user --help
``` ```
**Warning**: Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user. Upon a user's first login, they will be asked to confirm their email address. This requires that email sending is [configured](./configuring-playbook-email.md). You can also consult the [Working around email deliverability issues](./configuring-playbook-matrix-authentication-service.md#working-around-email-deliverability-issues) section for more information. **Warning**: Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user. Upon a user's first login, they will be asked to confirm their email address. This requires that email sending is [configured](./configuring-playbook-email.md). You can also consult the [Working around email deliverability issues](./configuring-playbook-matrix-authentication-service.md#working-around-email-deliverability-issues) section for more information.
## Managing users via a Web UI ## Managing users via a Web UI
To manage users more easily (via a web user-interace), you can install [Synapse Admin](configuring-playbook-synapse-admin.md). To manage users more easily (via a web user-interace), you can install [Synapse Admin](configuring-playbook-synapse-admin.md).
**Warning**: If you're using [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md), note that user management via synapse-admin is not fully working yet. See the [Expectations](configuring-playbook-matrix-authentication-service.md#expectations) section for more information. **Warning**: If you're using [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md), note that user management via synapse-admin is not fully working yet. See the [Expectations](configuring-playbook-matrix-authentication-service.md#expectations) section for more information.
## Letting certain users register on your private server ## Letting certain users register on your private server

View File

@ -2,14 +2,16 @@
## Option 1 (if you are using the integrated Postgres database): ## Option 1 (if you are using the integrated Postgres database):
You can reset a user's password via the Ansible playbook (make sure to edit the `<your-username>` and `<your-password>` part below): **Notes**:
- Make sure to adjust `USERNAME_HERE` and `PASSWORD_HERE`
- For `USERNAME_HERE`, use a plain username like `john`, not a full identifier (`@user:example.com`)
You can reset a user's password via the Ansible playbook:
``` ```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-username> password=<your-password>' --tags=update-user-password ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=USERNAME_HERE password=PASSWORD_HERE' --tags=update-user-password
``` ```
**Note**: `<your-username>` is just a plain username (like `john`), not your full `@<username>:example.com` identifier.
**You can then log in with that user** via Element Web that this playbook has created for you at a URL like this: `https://element.example.com/`. **You can then log in with that user** via Element Web that this playbook has created for you at a URL like this: `https://element.example.com/`.

View File

@ -436,11 +436,13 @@ devture_systemd_service_manager_services_list_auto: |
+ +
([{'name': (keydb_identifier + '.service'), 'priority': 750, 'groups': ['matrix', 'keydb']}] if keydb_enabled else []) ([{'name': (keydb_identifier + '.service'), 'priority': 750, 'groups': ['matrix', 'keydb']}] if keydb_enabled else [])
+ +
([{'name': (valkey_identifier + '.service'), 'priority': 750, 'groups': ['matrix', 'valkey']}] if valkey_enabled else [])
+
([{'name': 'matrix-pantalaimon.service', 'priority': 4000, 'groups': ['matrix', 'pantalaimon']}] if matrix_pantalaimon_enabled else []) ([{'name': 'matrix-pantalaimon.service', 'priority': 4000, 'groups': ['matrix', 'pantalaimon']}] if matrix_pantalaimon_enabled else [])
+ +
([{'name': 'matrix-element-call.service', 'priority': 4000, 'groups': ['matrix', 'element-call']}] if matrix_element_call_enabled else []) ([{'name': 'matrix-element-call.service', 'priority': 4000, 'groups': ['matrix', 'element-call']}] if matrix_element_call_enabled else [])
+ +
([{'name': 'matrix-jwt-service.service', 'priority': 3000, 'groups': ['matrix', 'jwt-service']}] if matrix_jwt_service_enabled else []) ([{'name': 'matrix-livekit-jwt-service.service', 'priority': 3500, 'groups': ['matrix', 'livekit-jwt-service']}] if matrix_livekit_jwt_service_enabled else [])
+ +
([{'name': (livekit_server_identifier + '.service'), 'priority': 3000, 'groups': ['matrix', 'livekit-server']}] if livekit_server_enabled else []) ([{'name': (livekit_server_identifier + '.service'), 'priority': 3000, 'groups': ['matrix', 'livekit-server']}] if livekit_server_enabled else [])
+ +
@ -2209,12 +2211,14 @@ matrix_hookshot_systemd_wanted_services_list: |
([(redis_identifier + '.service')] if redis_enabled and matrix_hookshot_cache_redis_host == redis_identifier else []) ([(redis_identifier + '.service')] if redis_enabled and matrix_hookshot_cache_redis_host == redis_identifier else [])
+ +
([(keydb_identifier + '.service')] if keydb_enabled and matrix_hookshot_cache_redis_host == keydb_identifier else []) ([(keydb_identifier + '.service')] if keydb_enabled and matrix_hookshot_cache_redis_host == keydb_identifier else [])
+
([(valkey_identifier + '.service')] if valkey_enabled and matrix_hookshot_cache_redis_host == valkey_identifier else [])
}} }}
# Hookshot's experimental encryption feature (and possibly others) may benefit from Redis, if available. # Hookshot's experimental encryption feature (and possibly others) may benefit from Redis, if available.
# We only connect to Redis if encryption is enabled (not for everyone who has Redis enabled), # We only connect to Redis if encryption is enabled (not for everyone who has Redis enabled),
# because connectivity is still potentially troublesome and is to be investigated. # because connectivity is still potentially troublesome and is to be investigated.
matrix_hookshot_cache_redis_host: "{{ redis_identifier if redis_enabled and matrix_hookshot_experimental_encryption_enabled else (keydb_identifier if keydb_enabled and matrix_hookshot_experimental_encryption_enabled else '') }}" matrix_hookshot_cache_redis_host: "{{ valkey_identifier if valkey_enabled else (redis_identifier if redis_enabled else (keydb_identifier if keydb_enabled else '')) }}"
matrix_hookshot_container_network: "{{ matrix_addons_container_network }}" matrix_hookshot_container_network: "{{ matrix_addons_container_network }}"
@ -2227,6 +2231,8 @@ matrix_hookshot_container_additional_networks_auto: |
+ +
([keydb_container_network] if keydb_enabled and matrix_hookshot_cache_redis_host == keydb_identifier else []) ([keydb_container_network] if keydb_enabled and matrix_hookshot_cache_redis_host == keydb_identifier else [])
+ +
([valkey_container_network] if valkey_enabled and matrix_hookshot_cache_redis_host == valkey_identifier else [])
+
([matrix_playbook_reverse_proxyable_services_additional_network] if matrix_playbook_reverse_proxyable_services_additional_network and matrix_hookshot_container_labels_traefik_enabled else []) ([matrix_playbook_reverse_proxyable_services_additional_network] if matrix_playbook_reverse_proxyable_services_additional_network and matrix_hookshot_container_labels_traefik_enabled else [])
) | unique ) | unique
}} }}
@ -4399,11 +4405,11 @@ ntfy_visitor_request_limit_exempt_hosts_hostnames_auto: |
###################################################################### ######################################################################
# #
# etke/redis # redis
# #
###################################################################### ######################################################################
redis_enabled: "{{ not keydb_enabled and (matrix_synapse_workers_enabled or (matrix_hookshot_enabled and matrix_hookshot_experimental_encryption_enabled)) }}" redis_enabled: "{{ not (keydb_enabled or valkey_enabled) and (matrix_synapse_workers_enabled or (matrix_hookshot_enabled and matrix_hookshot_experimental_encryption_enabled)) }}"
redis_identifier: matrix-redis redis_identifier: matrix-redis
@ -4414,7 +4420,7 @@ redis_base_path: "{{ matrix_base_data_path }}/redis"
###################################################################### ######################################################################
# #
# /etke/redis # /redis
# #
###################################################################### ######################################################################
@ -4424,7 +4430,7 @@ redis_base_path: "{{ matrix_base_data_path }}/redis"
# #
###################################################################### ######################################################################
keydb_enabled: "{{ matrix_synapse_workers_enabled or (matrix_hookshot_enabled and matrix_hookshot_experimental_encryption_enabled) or matrix_element_call_enabled }}" keydb_enabled: false
keydb_identifier: matrix-keydb keydb_identifier: matrix-keydb
@ -4448,6 +4454,31 @@ keydb_arch: |-
# #
###################################################################### ######################################################################
######################################################################
#
# valkey
#
######################################################################
valkey_enabled: "{{ matrix_synapse_workers_enabled or (matrix_hookshot_enabled and matrix_hookshot_experimental_encryption_enabled) or matrix_element_call_enabled }}"
valkey_identifier: matrix-valkey
valkey_uid: "{{ matrix_user_uid }}"
valkey_gid: "{{ matrix_user_gid }}"
valkey_base_path: "{{ matrix_base_data_path }}/valkey"
valkey_arch: "{{ matrix_architecture }}"
######################################################################
#
# valkey
#
######################################################################
###################################################################### ######################################################################
# #
# matrix-client-element # matrix-client-element
@ -4678,6 +4709,8 @@ matrix_synapse_container_additional_networks_auto: |
+ +
([keydb_container_network] if matrix_synapse_redis_enabled and matrix_synapse_redis_host == keydb_identifier else []) ([keydb_container_network] if matrix_synapse_redis_enabled and matrix_synapse_redis_host == keydb_identifier else [])
+ +
([valkey_container_network] if matrix_synapse_redis_enabled and matrix_synapse_redis_host == valkey_identifier else [])
+
([exim_relay_container_network] if (exim_relay_enabled and matrix_synapse_email_enabled and matrix_synapse_email_smtp_host == exim_relay_identifier and matrix_synapse_container_network != exim_relay_container_network) else []) ([exim_relay_container_network] if (exim_relay_enabled and matrix_synapse_email_enabled and matrix_synapse_email_smtp_host == exim_relay_identifier and matrix_synapse_container_network != exim_relay_container_network) else [])
+ +
([matrix_ma1sd_container_network] if (matrix_ma1sd_enabled and matrix_synapse_account_threepid_delegates_msisdn == matrix_synapse_account_threepid_delegates_msisdn_mas1sd_url and matrix_synapse_container_network != matrix_ma1sd_container_network) else []) ([matrix_ma1sd_container_network] if (matrix_ma1sd_enabled and matrix_synapse_account_threepid_delegates_msisdn == matrix_synapse_account_threepid_delegates_msisdn_mas1sd_url and matrix_synapse_container_network != matrix_ma1sd_container_network) else [])
@ -4765,6 +4798,8 @@ matrix_synapse_systemd_required_services_list_auto: |
+ +
([keydb_identifier ~ '.service'] if matrix_synapse_redis_enabled and matrix_synapse_redis_host == keydb_identifier else []) ([keydb_identifier ~ '.service'] if matrix_synapse_redis_enabled and matrix_synapse_redis_host == keydb_identifier else [])
+ +
([valkey_identifier ~ '.service'] if matrix_synapse_redis_enabled and matrix_synapse_redis_host == valkey_identifier else [])
+
(['matrix-goofys.service'] if matrix_s3_media_store_enabled else []) (['matrix-goofys.service'] if matrix_s3_media_store_enabled else [])
+ +
(['matrix-authentication-service.service'] if (matrix_authentication_service_enabled and matrix_synapse_experimental_features_msc3861_enabled) else []) (['matrix-authentication-service.service'] if (matrix_authentication_service_enabled and matrix_synapse_experimental_features_msc3861_enabled) else [])
@ -4778,9 +4813,9 @@ matrix_synapse_systemd_wanted_services_list_auto: |
}} }}
# Synapse workers (used for parallel load-scaling) need Redis for IPC. # Synapse workers (used for parallel load-scaling) need Redis for IPC.
matrix_synapse_redis_enabled: "{{ redis_enabled or keydb_enabled }}" matrix_synapse_redis_enabled: "{{ redis_enabled or keydb_enabled or valkey_enabled }}"
matrix_synapse_redis_host: "{{ redis_identifier if redis_enabled else (keydb_identifier if keydb_enabled else '') }}" matrix_synapse_redis_host: "{{ valkey_identifier if valkey_enabled else (redis_identifier if redis_enabled else (keydb_identifier if keydb_enabled else '')) }}"
matrix_synapse_redis_password: "{{ redis_connection_password if redis_enabled else (keydb_connection_password if keydb_enabled else '') }}" matrix_synapse_redis_password: "{{ valkey_connection_password if valkey_enabled else (redis_connection_password if redis_enabled else (keydb_connection_password if keydb_enabled else '')) }}"
matrix_synapse_container_extra_arguments_auto: "{{ matrix_homeserver_container_extra_arguments_auto }}" matrix_synapse_container_extra_arguments_auto: "{{ matrix_homeserver_container_extra_arguments_auto }}"
matrix_synapse_app_service_config_files_auto: "{{ matrix_homeserver_app_service_config_files_auto }}" matrix_synapse_app_service_config_files_auto: "{{ matrix_homeserver_app_service_config_files_auto }}"
@ -5924,7 +5959,7 @@ matrix_static_files_file_matrix_client_property_org_matrix_msc4143_rtc_foci_enab
matrix_static_files_file_matrix_client_property_org_matrix_msc4143_rtc_foci_auto: |- matrix_static_files_file_matrix_client_property_org_matrix_msc4143_rtc_foci_auto: |-
{{ {{
( (
[{'type': 'livekit', 'livekit_service_url': matrix_jwt_service_url}] if matrix_jwt_service_enabled else [] [{'type': 'livekit', 'livekit_service_url': matrix_livekit_jwt_service_public_url}] if matrix_livekit_jwt_service_enabled else []
) )
}} }}
@ -6103,45 +6138,61 @@ livekit_server_container_labels_traefik_docker_network: "{{ matrix_playbook_reve
livekit_server_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}" livekit_server_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
livekit_server_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}" livekit_server_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
livekit_server_config_keys_auto: |-
{{
{}
| combine(
{matrix_livekit_jwt_service_environment_variable_livekit_key: matrix_livekit_jwt_service_environment_variable_livekit_secret}
if matrix_livekit_jwt_service_enabled else {}
)
}}
######################################################################## ########################################################################
# # # #
# /livekit-server # # /livekit-server #
# # # #
######################################################################## ########################################################################
########################################################################
# #
# matrix-jwt-service #
# #
########################################################################
matrix_jwt_service_enabled: "{{ matrix_element_call_enabled }}"
matrix_jwt_service_version: "latest-ci" # Default version; can be overridden in host_vars
matrix_jwt_service_scheme: "https" # Scheme for Element Call (e.g., https)
matrix_jwt_service_hostname: "sfu-jwt.{{ matrix_domain }}" # Default hostname; should be overridden in host_vars if different
matrix_jwt_service_path_prefix: "/" # Path prefix for Element Call
matrix_jwt_service_base_path: "{{ matrix_base_data_path }}/matrix-jwt-service" # Base path for storing Element Call-related files
matrix_jwt_service_container_image: "ghcr.io/element-hq/lk-jwt-service:{{ matrix_jwt_service_version }}"
matrix_jwt_service_container_image_name_prefix: ghcr.io/
matrix_jwt_service_container_image_registry_prefix: ghcr.io/
matrix_jwt_service_container_image_force_pull: true
# Docker network configuration for JWT Service
matrix_jwt_service_container_network: "{{ matrix_addons_container_network }}"
matrix_jwt_service_container_additional_networks: "{{ [matrix_playbook_reverse_proxyable_services_additional_network] if (matrix_jwt_service_container_labels_traefik_enabled and matrix_playbook_reverse_proxyable_services_additional_network) else [] }}"
# Traefik Configuration for JWT Service
matrix_jwt_service_container_labels_traefik_enabled: "{{ matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] }}"
matrix_jwt_service_container_labels_traefik_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
matrix_jwt_service_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
matrix_jwt_service_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
# JWT Service Configuration
matrix_jwt_service_url: "https://sfu-jwt.{{ matrix_domain }}" # Default JWT service URL; adjust as needed
######################################################################## ########################################################################
# # # #
# /matrix-jwt-service # # matrix-livekit-jwt-service #
# #
########################################################################
matrix_livekit_jwt_service_enabled: "{{ matrix_element_call_enabled and livekit_server_enabled }}"
matrix_livekit_jwt_service_scheme: "{{ 'https' if matrix_playbook_ssl_enabled else 'http' }}"
matrix_livekit_jwt_service_hostname: "{{ matrix_server_fqn_matrix }}"
matrix_livekit_jwt_service_path_prefix: "/lk-jwt-service"
matrix_livekit_jwt_service_container_image_self_build: "{{ matrix_architecture not in ['amd64', 'arm64'] }}"
matrix_livekit_jwt_service_container_network: "{{ matrix_addons_container_network }}"
matrix_livekit_jwt_service_container_additional_networks_auto: |
{{
(
([matrix_playbook_reverse_proxyable_services_additional_network] if (matrix_livekit_jwt_service_container_labels_traefik_enabled and matrix_playbook_reverse_proxyable_services_additional_network) else [])
+
([livekit_server_container_network] if livekit_server_enabled and (matrix_livekit_jwt_service_environment_variable_livekit_url == livekit_server_websocket_container_url and livekit_server_container_network != matrix_livekit_jwt_service_container_network) else [])
) | unique
}}
matrix_livekit_jwt_service_container_labels_traefik_enabled: "{{ matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] }}"
matrix_livekit_jwt_service_container_labels_traefik_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
matrix_livekit_jwt_service_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
matrix_livekit_jwt_service_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
matrix_livekit_jwt_service_environment_variable_livekit_url: "{{ livekit_server_websocket_container_url }}"
matrix_livekit_jwt_service_environment_variable_livekit_key: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'lk.key', rounds=655555) | to_uuid }}"
matrix_livekit_jwt_service_environment_variable_livekit_secret: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'lk.secret', rounds=655555) | to_uuid }}"
########################################################################
# #
# /matrix-livekit-jwt-service #
# # # #
######################################################################## ########################################################################

View File

@ -75,3 +75,6 @@
- src: git+https://github.com/mother-of-all-self-hosting/ansible-role-traefik-certs-dumper.git - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-traefik-certs-dumper.git
version: v2.8.3-5 version: v2.8.3-5
name: traefik_certs_dumper name: traefik_certs_dumper
- src: git+https://github.com/mother-of-all-self-hosting/ansible-role-valkey.git
version: v8.0.1-0
name: valkey

View File

@ -6,6 +6,6 @@
} }
}, },
"livekit": { "livekit": {
"livekit_service_url": "{{ matrix_jwt_service_url }}" "livekit_service_url": "{{ matrix_livekit_jwt_service_public_url }}"
} }
} }

View File

@ -1,117 +0,0 @@
---
# Enable or disable matrix-element-call deployment
matrix_jwt_service_enabled: false
# Base path configuration
matrix_jwt_service_base_path: "{{ matrix_base_data_path }}/jwt-service"
# Docker network configuration
matrix_jwt_service_container_network: ''
matrix_jwt_service_container_http_host_bind_port: '8881'
matrix_jwt_service_container_additional_networks: [] # No additional networks by default
# Docker images
matrix_jwt_service_image: "ghcr.io/element-hq/lk-jwt-service:latest-ci"
# Ports
matrix_jwt_service_port: "8881"
# jwt configuration
matrix_jwt_service_hostname: "sfu-jwt.{{ matrix_domain }}"
matrix_jwt_service_url: "https://sfu-jwt.{{ matrix_domain }}"
# Traefik Configuration for JWT Service
matrix_jwt_service_container_labels_traefik_enabled: true
matrix_jwt_service_container_labels_traefik_docker_network: "{{ matrix_jwt_service_container_network }}"
matrix_jwt_service_container_labels_traefik_hostname: "{{ matrix_jwt_service_hostname }}"
# The path prefix must either be `/` or not end with a slash (e.g. `/element`).
matrix_jwt_service_container_labels_traefik_path_prefix: "{{ matrix_jwt_service_path_prefix }}"
matrix_jwt_service_container_labels_traefik_rule: "Host(`{{ matrix_jwt_service_container_labels_traefik_hostname }}`){% if matrix_jwt_service_container_labels_traefik_path_prefix != '/' %} && PathPrefix(`{{ matrix_jwt_service_container_labels_traefik_path_prefix }}`){% endif %}"
matrix_jwt_service_container_labels_traefik_priority: 0
matrix_jwt_service_container_labels_traefik_entrypoints: web-secure
matrix_jwt_service_container_labels_traefik_tls: "{{ matrix_jwt_service_container_labels_traefik_entrypoints != 'web' }}"
matrix_jwt_service_container_labels_traefik_tls_certResolver: default # noqa var-naming
# Controls which additional headers to attach to all HTTP responses.
# To add your own headers, use `matrix_jwt_service_container_labels_traefik_additional_response_headers_custom`
matrix_jwt_service_container_labels_traefik_additional_response_headers: "{{ matrix_jwt_service_container_labels_traefik_additional_response_headers_auto | combine(matrix_jwt_service_container_labels_traefik_additional_response_headers_custom) }}"
matrix_jwt_service_container_labels_traefik_additional_response_headers_auto: |
{{
{}
| combine ({'X-XSS-Protection': matrix_jwt_service_http_header_xss_protection} if matrix_jwt_service_http_header_xss_protection else {})
| combine ({'X-Frame-Options': matrix_jwt_service_http_header_frame_options} if matrix_jwt_service_http_header_frame_options else {})
| combine ({'X-Content-Type-Options': matrix_jwt_service_http_header_content_type_options} if matrix_jwt_service_http_header_content_type_options else {})
| combine ({'Content-Security-Policy': matrix_jwt_service_http_header_content_security_policy} if matrix_jwt_service_http_header_content_security_policy else {})
| combine ({'Permission-Policy': matrix_jwt_service_http_header_content_permission_policy} if matrix_jwt_service_http_header_content_permission_policy else {})
| combine ({'Strict-Transport-Security': matrix_jwt_service_http_header_strict_transport_security} if matrix_jwt_service_http_header_strict_transport_security and matrix_jwt_service_container_labels_traefik_tls else {})
}}
matrix_jwt_service_container_labels_traefik_additional_response_headers_custom: {}
# matrix_client_element_container_labels_additional_labels contains a multiline string with additional labels to add to the container label file.
# See `../templates/labels.j2` for details.
#
# Example:
# matrix_client_element_container_labels_additional_labels: |
# my.label=1
# another.label="here"
matrix_jwt_service_container_labels_additional_labels: ''
# A list of extra arguments to pass to the container
matrix_jwt_service_container_extra_arguments: []
# Additional environment variables for the container
matrix_jwt_service_environment_variables_additional: {}
# List of systemd services that matrix-element-call.service depends on
matrix_jwt_service_systemd_required_services_list: "{{ [devture_systemd_docker_base_docker_service_name] if devture_systemd_docker_base_docker_service_name else [] }}"
# Specifies the value of the `X-XSS-Protection` header
# Stops pages from loading when they detect reflected cross-site scripting (XSS) attacks.
#
# Learn more about it is here:
# - https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection
# - https://portswigger.net/web-security/cross-site-scripting/reflected
matrix_jwt_service_http_header_xss_protection: ''
# Specifies the value of the `X-Frame-Options` header which controls whether framing can happen.
# See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options
matrix_jwt_service_http_header_frame_options: ''
# Specifies the value of the `X-Content-Type-Options` header.
# See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options
matrix_jwt_service_http_header_content_type_options: ''
# Specifies the value of the `Content-Security-Policy` header.
# See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy
matrix_jwt_service_http_header_content_security_policy: ''
# Specifies the value of the `Permission-Policy` header.
# See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permission-Policy
matrix_jwt_service_http_header_content_permission_policy: ''
# Specifies the value of the `Strict-Transport-Security` header.
# See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security
matrix_jwt_service_http_header_strict_transport_security: ''
# Controls whether to send a "Permissions-Policy interest-cohort=();" header along with all responses
#
# Learn more about what it is here:
# - https://www.eff.org/deeplinks/2021/03/googles-floc-terrible-idea
# - https://paramdeo.com/blog/opting-your-website-out-of-googles-floc-network
# - https://amifloced.org/
#
# Of course, a better solution is to just stop using browsers (like Chrome), which participate in such tracking practices.
# See: `matrix_jwt_service_content_permission_policy`
matrix_jwt_service_floc_optout_enabled: false
# Controls if HSTS preloading is enabled
#
# In its strongest and recommended form, the [HSTS policy](https://www.chromium.org/hsts) includes all subdomains, and
# indicates a willingness to be "preloaded" into browsers:
# `Strict-Transport-Security: max-age=31536000; includeSubDomains; preload`
# For more information visit:
# - https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security
# - https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security
# - https://hstspreload.org/#opt-in
# See: `matrix_jwt_service_http_header_strict_transport_security`
matrix_jwt_service_hsts_preload_enabled: true

View File

@ -1,46 +0,0 @@
---
# roles/custom/matrix-jwt-service/tasks/install.yml
# Ensure Required Directories Exist
- name: Ensure matrix-jwt-service paths exist
ansible.builtin.file:
path: "{{ item.path }}"
state: directory
mode: 0750
owner: "{{ matrix_user_username }}"
group: "{{ matrix_user_groupname }}"
with_items:
- path: "{{ matrix_jwt_service_base_path }}"
- name: Ensure matrix-jwt-service environment file is in place
ansible.builtin.template:
src: "{{ role_path }}/templates/env.j2"
dest: "{{ matrix_jwt_service_base_path }}/env"
mode: 0640
owner: "{{ matrix_user_username }}"
group: "{{ matrix_user_groupname }}"
- name: Ensure JWT Service labels file is in place
ansible.builtin.template:
src: "{{ role_path }}/templates/labels.j2"
dest: "{{ matrix_jwt_service_base_path }}/labels"
mode: 0640
owner: "{{ matrix_user_username }}"
group: "{{ matrix_user_groupname }}"
# Ensure Docker Images are Pulled
- name: Ensure jwt-service Docker image is pulled
community.docker.docker_image:
name: "{{ matrix_jwt_service_image }}"
source: pull
register: jwt_image_result
retries: 3
delay: 10
until: jwt_image_result is not failed
# Systemd Services for JWT Service
- name: Ensure jwt-service systemd service is installed
ansible.builtin.template:
src: "{{ role_path }}/templates/systemd/matrix-jwt-service.service.j2"
dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-jwt-service.service"
mode: 0644

View File

@ -1,22 +0,0 @@
---
# Uninstall tasks for matrix-jwt-service
- name: Stop and remove jwt-service container
community.docker.docker_container:
name: "matrix-jwt-service"
state: absent
- name: Remove jwt-service systemd service
ansible.builtin.file:
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-jwt-service.service"
state: absent
- name: Remove matrix-jwt-service configuration files
ansible.builtin.file:
path: "{{ matrix_jwt_service_base_path }}"
state: absent
- name: Reload systemd daemon
ansible.builtin.systemd:
daemon_reload: true

View File

@ -1,12 +0,0 @@
---
# Validate configuration for matrix-jwt-service
- name: Fail if required matrix-jwt-service settings are not defined
ansible.builtin.fail:
msg: >
You need to define a required configuration setting (`{{ item.name }}`).
when: "item.when | bool and vars[item.name] == ''"
with_items:
- {'name': 'matrix_jwt_service_base_path', when: true}
- {'name': 'matrix_jwt_service_container_network', when: true}
- {'name': 'matrix_jwt_service_image', when: true}

View File

@ -1,4 +0,0 @@
# Environment variables for JWT Service
LIVEKIT_KEY=devkey
LIVEKIT_URL=wss://{{ livekit_server_hostname }}:443
LIVEKIT_SECRET={{ livekit_server_dev_key }}

View File

@ -1,46 +0,0 @@
{% if matrix_element_call_container_labels_traefik_enabled %}
traefik.enable=true
# Network configuration for Traefik
{% if matrix_jwt_service_container_labels_traefik_docker_network %}
traefik.docker.network={{ matrix_jwt_service_container_labels_traefik_docker_network }}
{% endif %}
traefik.http.services.matrix-jwt-service.loadbalancer.server.port=8080
{% set middlewares = [] %}
# Path prefix handling for JWT
{% if matrix_jwt_service_container_labels_traefik_path_prefix != '/' %}
traefik.http.middlewares.matrix-jwt-service-slashless-redirect.redirectregex.regex=({{ matrix_jwt_service_container_labels_traefik_path_prefix | quote }})$
traefik.http.middlewares.matrix-jwt-service-slashless-redirect.redirectregex.replacement=${1}/
{% set middlewares = middlewares + ['matrix-jwt-service-slashless-redirect'] %}
traefik.http.middlewares.matrix-jwt-service-strip-prefix.stripprefix.prefixes={{ matrix_jwt_service_container_labels_traefik_path_prefix }}
{% set middlewares = middlewares + ['matrix-jwt-service-strip-prefix'] %}
{% endif %}
{% if matrix_jwt_service_container_labels_traefik_additional_response_headers.keys() | length > 0 %}
{% for name, value in matrix_jwt_service_container_labels_traefik_additional_response_headers.items() %}
traefik.http.middlewares.matrix-jwt-service-add-headers.headers.customresponseheaders.{{ name }}={{ value }}
{% endfor %}
{% set middlewares = middlewares + ['matrix-jwt-service-add-headers'] %}
{% endif %}
traefik.http.routers.matrix-jwt-service.rule={{ matrix_jwt_service_container_labels_traefik_rule }}
{% if matrix_jwt_service_container_labels_traefik_priority | int > 0 %}
traefik.http.routers.matrix-jwt-service.priority={{ matrix_jwt_service_container_labels_traefik_priority }}
{% endif %}
traefik.http.routers.matrix-jwt-service.service=matrix-jwt-service
{% if middlewares | length > 0 %}
traefik.http.routers.matrix-jwt-service.middlewares={{ middlewares | join(',') }}
{% endif %}
traefik.http.routers.matrix-jwt-service.entrypoints={{ matrix_jwt_service_container_labels_traefik_entrypoints }}
traefik.http.routers.matrix-jwt-service.tls={{ matrix_jwt_service_container_labels_traefik_tls | to_json }}
{% if matrix_jwt_service_container_labels_traefik_tls %}
traefik.http.routers.matrix-jwt-service.tls.certResolver={{ matrix_jwt_service_container_labels_traefik_tls_certResolver }}
{% endif %}
{% endif %}
{{ matrix_jwt_service_container_labels_additional_labels }}

View File

@ -0,0 +1,81 @@
---
# Project source code URL: https://github.com/element-hq/lk-jwt-service
matrix_livekit_jwt_service_enabled: false
matrix_livekit_jwt_service_scheme: https
matrix_livekit_jwt_service_hostname: ""
matrix_livekit_jwt_service_path_prefix: "/lk-jwt-service"
matrix_livekit_jwt_service_base_path: "{{ matrix_base_data_path }}/livekit-jwt-service"
matrix_livekit_jwt_service_container_network: ''
matrix_livekit_jwt_service_container_http_host_bind_port: ''
matrix_livekit_jwt_service_container_additional_networks: "{{ (matrix_livekit_jwt_service_container_additional_networks_auto + matrix_livekit_jwt_service_container_additional_networks_custom) | unique }}"
matrix_livekit_jwt_service_container_additional_networks_auto: []
matrix_livekit_jwt_service_container_additional_networks_custom: []
# renovate: datasource=docker depName=ghcr.io/element-hq/lk-jwt-service
matrix_livekit_jwt_service_version: latest-ci
matrix_livekit_jwt_service_container_image_self_build: false
matrix_livekit_jwt_service_container_repo: "https://github.com/element-hq/lk-jwt-service.git"
matrix_livekit_jwt_service_container_repo_version: "{{ 'main' if matrix_livekit_jwt_service_version in ['latest', 'latest-ci'] else livekit_server_version }}"
matrix_livekit_jwt_service_container_src_files_path: "{{ matrix_livekit_jwt_service_base_path }}/container-src"
matrix_livekit_jwt_service_container_image: "{{ matrix_livekit_jwt_service_container_image_name_prefix }}element-hq/lk-jwt-service:{{ matrix_livekit_jwt_service_version }}"
matrix_livekit_jwt_service_container_image_name_prefix: "{{ 'localhost/' if matrix_livekit_jwt_service_container_image_self_build else 'ghcr.io/' }}"
matrix_livekit_jwt_service_container_image_force_pull: "{{ matrix_livekit_jwt_service_container_image.endswith(':latest') }}"
matrix_livekit_jwt_service_container_labels_traefik_enabled: true
matrix_livekit_jwt_service_container_labels_traefik_docker_network: "{{ matrix_livekit_jwt_service_container_network }}"
matrix_livekit_jwt_service_container_labels_traefik_hostname: "{{ matrix_livekit_jwt_service_hostname }}"
# The path prefix must either be `/` or not end with a slash (e.g. `/lk-jwt-service`).
matrix_livekit_jwt_service_container_labels_traefik_path_prefix: "{{ matrix_livekit_jwt_service_path_prefix }}"
matrix_livekit_jwt_service_container_labels_traefik_rule: "Host(`{{ matrix_livekit_jwt_service_container_labels_traefik_hostname }}`){% if matrix_livekit_jwt_service_container_labels_traefik_path_prefix != '/' %} && PathPrefix(`{{ matrix_livekit_jwt_service_container_labels_traefik_path_prefix }}`){% endif %}"
matrix_livekit_jwt_service_container_labels_traefik_priority: 0
matrix_livekit_jwt_service_container_labels_traefik_entrypoints: web-secure
matrix_livekit_jwt_service_container_labels_traefik_tls: "{{ matrix_livekit_jwt_service_container_labels_traefik_entrypoints != 'web' }}"
matrix_livekit_jwt_service_container_labels_traefik_tls_certResolver: default # noqa var-naming
# Controls which additional headers to attach to all HTTP responses.
# To add your own headers, use `matrix_livekit_jwt_service_container_labels_traefik_additional_response_headers_custom`
matrix_livekit_jwt_service_container_labels_traefik_additional_response_headers: "{{ matrix_livekit_jwt_service_container_labels_traefik_additional_response_headers_auto | combine(matrix_livekit_jwt_service_container_labels_traefik_additional_response_headers_custom) }}"
matrix_livekit_jwt_service_container_labels_traefik_additional_response_headers_auto: {}
matrix_livekit_jwt_service_container_labels_traefik_additional_response_headers_custom: {}
# matrix_client_element_container_labels_additional_labels contains a multiline string with additional labels to add to the container label file.
# See `../templates/labels.j2` for details.
#
# Example:
# matrix_client_element_container_labels_additional_labels: |
# my.label=1
# another.label="here"
matrix_livekit_jwt_service_container_labels_additional_labels: ''
# A list of extra arguments to pass to the container
matrix_livekit_jwt_service_container_extra_arguments: []
# Controls the LK_JWT_PORT environment variable
matrix_livekit_jwt_service_environment_variable_lk_jwt_port: 8080
# Controls the LIVEKIT_KEY environment variable
matrix_livekit_jwt_service_environment_variable_livekit_key: ""
# Controls the LIVEKIT_URL environment variable
matrix_livekit_jwt_service_environment_variable_livekit_url: ""
# Controls the LIVEKIT_SECRET environment variable
matrix_livekit_jwt_service_environment_variable_livekit_secret: ""
# Additional environment variables for the container
matrix_livekit_jwt_service_environment_variables_additional: {}
# List of systemd services that LiveKit JWT Service service depends on
matrix_livekit_jwt_service_systemd_required_services_list: "{{ matrix_livekit_jwt_service_systemd_required_services_list_default + matrix_livekit_jwt_service_systemd_required_services_list_auto + matrix_livekit_jwt_service_systemd_required_services_list_custom }}"
matrix_livekit_jwt_service_systemd_required_services_list_default: "{{ [devture_systemd_docker_base_docker_service_name] if devture_systemd_docker_base_docker_service_name else [] }}"
matrix_livekit_jwt_service_systemd_required_services_list_auto: []
matrix_livekit_jwt_service_systemd_required_services_list_custom: []

View File

@ -0,0 +1,69 @@
---
- name: Ensure LiveKit JWT Service paths exist
ansible.builtin.file:
path: "{{ item.path }}"
state: directory
mode: 0750
owner: "{{ matrix_user_username }}"
group: "{{ matrix_user_groupname }}"
with_items:
- path: "{{ matrix_livekit_jwt_service_base_path }}"
- name: Ensure LiveKit JWT Service support files installed
ansible.builtin.template:
src: "{{ role_path }}/templates/{{ item }}.j2"
dest: "{{ matrix_livekit_jwt_service_base_path }}/{{ item }}"
mode: 0640
owner: "{{ matrix_user_username }}"
group: "{{ matrix_user_groupname }}"
with_items:
- env
- labels
- name: Ensure LiveKit JWT Service container image is pulled
community.docker.docker_image:
name: "{{ matrix_livekit_jwt_service_container_image }}"
source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
force_source: "{{ matrix_livekit_jwt_service_container_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_livekit_jwt_service_container_image_force_pull }}"
when: "not matrix_livekit_jwt_service_container_image_self_build | bool"
register: result
retries: "{{ devture_playbook_help_container_retries_count }}"
delay: "{{ devture_playbook_help_container_retries_delay }}"
until: result is not failed
- when: "matrix_livekit_jwt_service_container_image_self_build | bool"
block:
- name: Ensure LiveKit JWT Service repository is present on self-build
ansible.builtin.git:
repo: "{{ matrix_livekit_jwt_service_container_repo }}"
version: "{{ matrix_livekit_jwt_service_container_repo_version }}"
dest: "{{ matrix_livekit_jwt_service_container_src_files_path }}"
force: "yes"
become: true
become_user: "{{ matrix_user_username }}"
register: matrix_livekit_jwt_service_git_pull_results
- name: Ensure LiveKit JWT Service container image is built
community.docker.docker_image:
name: "{{ matrix_livekit_jwt_service_container_image }}"
source: build
force_source: "{{ matrix_livekit_jwt_service_git_pull_results.changed if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_livekit_jwt_service_git_pull_results.changed }}"
build:
dockerfile: Dockerfile
path: "{{ matrix_livekit_jwt_service_container_src_files_path }}"
pull: true
- name: Ensure LiveKit JWT Service container network is created
community.general.docker_network:
enable_ipv6: "{{ devture_systemd_docker_base_ipv6_enabled }}"
name: "{{ matrix_livekit_jwt_service_container_network }}"
driver: bridge
- name: Ensure LiveKit JWT Service systemd service is installed
ansible.builtin.template:
src: "{{ role_path }}/templates/systemd/matrix-livekit-jwt-service.service.j2"
dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-livekit-jwt-service.service"
mode: 0644

View File

@ -1,21 +1,20 @@
--- ---
# Main task file for matrix-element-call
- tags: - tags:
- setup-all - setup-all
- setup-jwt-service - setup-jwt-service
- install-all - install-all
- install-wt-service - install-livekit-jwt-service
block: block:
- when: matrix_jwt_service_enabled | bool - when: matrix_livekit_jwt_service_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml" ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
- when: matrix_jwt_service_enabled | bool - when: matrix_livekit_jwt_service_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/install.yml" ansible.builtin.include_tasks: "{{ role_path }}/tasks/install.yml"
- tags: - tags:
- setup-all - setup-all
- setup-jwt-service - setup-livekit-jwt-service
block: block:
- when: not matrix_jwt_service_enabled | bool - when: not matrix_livekit_jwt_service_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/uninstall.yml" ansible.builtin.include_tasks: "{{ role_path }}/tasks/uninstall.yml"

View File

@ -0,0 +1,25 @@
---
- name: Check existence of LiveKit JWT Service systemd service
ansible.builtin.stat:
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-livekit-jwt-service.service"
register: matrix_livekit_jwt_service_service_stat
- when: matrix_livekit_jwt_service_service_stat.stat.exists | bool
block:
- name: Ensure LiveKit JWT Service systemd service is stopped
ansible.builtin.service:
name: matrix-livekit-jwt-service
state: stopped
enabled: false
daemon_reload: true
- name: Ensure LiveKit JWT Service systemd service doesn't exist
ansible.builtin.file:
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-livekit-jwt-service.service"
state: absent
- name: Ensure LiveKit JWT Service paths don't exist
ansible.builtin.file:
path: "{{ matrix_livekit_jwt_service_base_path }}"
state: absent

View File

@ -0,0 +1,13 @@
---
- name: Fail if required LiveKit JWT Service settings are not defined
ansible.builtin.fail:
msg: >
You need to define a required configuration setting (`{{ item.name }}`).
when: "item.when | bool and vars[item.name] | length == 0"
with_items:
- {'name': 'matrix_livekit_jwt_service_hostname', when: true}
- {'name': 'matrix_livekit_jwt_service_container_network', when: true}
- {'name': 'matrix_livekit_jwt_service_environment_variable_livekit_key', when: true}
- {'name': 'matrix_livekit_jwt_service_environment_variable_livekit_url', when: true}
- {'name': 'matrix_livekit_jwt_service_environment_variable_livekit_secret', when: true}

View File

@ -0,0 +1,7 @@
LK_JWT_PORT={{ matrix_livekit_jwt_service_environment_variable_lk_jwt_port | int | to_json }}
LIVEKIT_KEY={{ matrix_livekit_jwt_service_environment_variable_livekit_key }}
LIVEKIT_URL={{ matrix_livekit_jwt_service_environment_variable_livekit_url }}
LIVEKIT_SECRET={{ matrix_livekit_jwt_service_environment_variable_livekit_secret }}
{{ matrix_livekit_jwt_service_environment_variables_additional }}

View File

@ -0,0 +1,48 @@
{% if matrix_element_call_container_labels_traefik_enabled %}
traefik.enable=true
traefik.docker.network={{ matrix_livekit_jwt_service_container_labels_traefik_docker_network }}
traefik.http.services.matrix-livekit-jwt-service.loadbalancer.server.port={{ matrix_livekit_jwt_service_environment_variable_lk_jwt_port }}
{% set middlewares = [] %}
{% if matrix_livekit_jwt_service_container_labels_traefik_path_prefix != '/' %}
traefik.http.middlewares.matrix-livekit-jwt-service-slashless-redirect.redirectregex.regex=({{ matrix_livekit_jwt_service_container_labels_traefik_path_prefix | quote }})$
traefik.http.middlewares.matrix-livekit-jwt-service-slashless-redirect.redirectregex.replacement=${1}/
{% set middlewares = middlewares + ['matrix-livekit-jwt-service-slashless-redirect'] %}
traefik.http.middlewares.matrix-livekit-jwt-service-strip-prefix.stripprefix.prefixes={{ matrix_livekit_jwt_service_container_labels_traefik_path_prefix }}
{% set middlewares = middlewares + ['matrix-livekit-jwt-service-strip-prefix'] %}
{% endif %}
{% if matrix_livekit_jwt_service_container_labels_traefik_additional_response_headers.keys() | length > 0 %}
{% for name, value in matrix_livekit_jwt_service_container_labels_traefik_additional_response_headers.items() %}
traefik.http.middlewares.matrix-livekit-jwt-service-add-headers.headers.customresponseheaders.{{ name }}={{ value }}
{% endfor %}
{% set middlewares = middlewares + ['matrix-livekit-jwt-service-add-headers'] %}
{% endif %}
traefik.http.routers.matrix-livekit-jwt-service.rule={{ matrix_livekit_jwt_service_container_labels_traefik_rule }}
{% if matrix_livekit_jwt_service_container_labels_traefik_priority | int > 0 %}
traefik.http.routers.matrix-livekit-jwt-service.priority={{ matrix_livekit_jwt_service_container_labels_traefik_priority }}
{% endif %}
traefik.http.routers.matrix-livekit-jwt-service.service=matrix-livekit-jwt-service
{% if middlewares | length > 0 %}
traefik.http.routers.matrix-livekit-jwt-service.middlewares={{ middlewares | join(',') }}
{% endif %}
traefik.http.routers.matrix-livekit-jwt-service.entrypoints={{ matrix_livekit_jwt_service_container_labels_traefik_entrypoints }}
traefik.http.routers.matrix-livekit-jwt-service.tls={{ matrix_livekit_jwt_service_container_labels_traefik_tls | to_json }}
{% if matrix_livekit_jwt_service_container_labels_traefik_tls %}
traefik.http.routers.matrix-livekit-jwt-service.tls.certResolver={{ matrix_livekit_jwt_service_container_labels_traefik_tls_certResolver }}
{% endif %}
{% endif %}
{{ matrix_livekit_jwt_service_container_labels_additional_labels }}

View File

@ -1,40 +1,42 @@
#jinja2: lstrip_blocks: "True" #jinja2: lstrip_blocks: "True"
[Unit] [Unit]
Description=Matrix JWT Service Description=Matrix LiveKit JWT Service
After=docker.service {% for service in matrix_livekit_jwt_service_systemd_required_services_list %}
Requires=docker.service After={{ service }}
Requires={{ service }}
{% endfor %}
[Service] [Service]
Type=simple Type=simple
Environment="HOME={{ devture_systemd_docker_base_systemd_unit_home_path }}" Environment="HOME={{ devture_systemd_docker_base_systemd_unit_home_path }}"
ExecStartPre=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} stop --time={{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-jwt-service 2>/dev/null || true' ExecStartPre=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} stop --time={{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-livekit-jwt-service 2>/dev/null || true'
ExecStartPre=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-jwt-service 2>/dev/null || true' ExecStartPre=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-livekit-jwt-service 2>/dev/null || true'
ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} create \ ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} create \
--rm \ --rm \
--name=matrix-jwt-service \ --name=matrix-livekit-jwt-service \
--log-driver=none \ --log-driver=none \
--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \ --user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
--cap-drop=ALL \ --cap-drop=ALL \
--network={{ matrix_jwt_service_container_network }} \ --network={{ matrix_livekit_jwt_service_container_network }} \
{% if matrix_jwt_service_container_http_host_bind_port %} {% if matrix_livekit_jwt_service_container_http_host_bind_port %}
-p {{ matrix_jwt_service_container_http_host_bind_port }}:8080 \ -p {{ matrix_livekit_jwt_service_container_http_host_bind_port }}:{{ matrix_livekit_jwt_service_environment_variable_lk_jwt_port }} \
{% endif %} {% endif %}
--env-file={{ matrix_jwt_service_base_path }}/env \ --env-file={{ matrix_livekit_jwt_service_base_path }}/env \
--label-file={{ matrix_jwt_service_base_path }}/labels \ --label-file={{ matrix_livekit_jwt_service_base_path }}/labels \
{{ matrix_jwt_service_image }} {{ matrix_livekit_jwt_service_container_image }}
{% for network in matrix_jwt_service_container_additional_networks %} {% for network in matrix_livekit_jwt_service_container_additional_networks %}
ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} network connect {{ network }} matrix-jwt-service ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} network connect {{ network }} matrix-livekit-jwt-service
{% endfor %} {% endfor %}
ExecStart={{ devture_systemd_docker_base_host_command_docker }} start --attach matrix-jwt-service ExecStart={{ devture_systemd_docker_base_host_command_docker }} start --attach matrix-livekit-jwt-service
ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} stop --time={{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-jwt-service 2>/dev/null || true' ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} stop --time={{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-livekit-jwt-service 2>/dev/null || true'
ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-jwt-service 2>/dev/null || true' ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-jwt-service 2>/dev/null || true'
Restart=always Restart=always
RestartSec=30 RestartSec=30
SyslogIdentifier=matrix-jwt-service SyslogIdentifier=matrix-livekit-jwt-service
[Install] [Install]
WantedBy=multi-user.target WantedBy=multi-user.target

View File

@ -0,0 +1,3 @@
---
matrix_livekit_jwt_service_public_url: "{{ matrix_livekit_jwt_service_scheme }}://{{ matrix_livekit_jwt_service_hostname }}"

View File

@ -12,7 +12,7 @@ livekit_server_gid: ''
livekit_server_base_path: "/{{ livekit_server_identifier }}" livekit_server_base_path: "/{{ livekit_server_identifier }}"
livekit_server_config_path: "{{ livekit_server_base_path }}/config" livekit_server_config_path: "{{ livekit_server_base_path }}/config"
# renovate: datasource=docker depName=livekit/livekit-server # renovate: datasource=docker depName=docker.io/livekit/livekit-server
livekit_server_version: v1.8.0 livekit_server_version: v1.8.0
livekit_server_scheme: https livekit_server_scheme: https
@ -73,11 +73,11 @@ livekit_server_container_labels_traefik_additional_response_headers_auto: |
}} }}
livekit_server_container_labels_traefik_additional_response_headers_custom: {} livekit_server_container_labels_traefik_additional_response_headers_custom: {}
# matrix_client_element_container_labels_additional_labels contains a multiline string with additional labels to add to the container label file. # livekit_server_container_labels_additional_labels contains a multiline string with additional labels to add to the container label file.
# See `../templates/labels.j2` for details. # See `../templates/labels.j2` for details.
# #
# Example: # Example:
# matrix_client_element_container_labels_additional_labels: | # livekit_server_container_labels_additional_labels: |
# my.label=1 # my.label=1
# another.label="here" # another.label="here"
livekit_server_container_labels_additional_labels: '' livekit_server_container_labels_additional_labels: ''
@ -88,8 +88,11 @@ livekit_server_container_extra_arguments: []
# Additional environment variables for the container # Additional environment variables for the container
livekit_server_environment_variables_additional: {} livekit_server_environment_variables_additional: {}
# List of systemd services that matrix-element-call.service depends on # List of systemd services that LiveKit Server service depends on
livekit_server_systemd_required_services_list: "{{ [devture_systemd_docker_base_docker_service_name] if devture_systemd_docker_base_docker_service_name else [] }}" livekit_server_systemd_required_services_list: "{{ livekit_server_systemd_required_services_list_default + livekit_server_systemd_required_services_list_auto + livekit_server_systemd_required_services_list_custom }}"
livekit_server_systemd_required_services_list_default: "{{ [devture_systemd_docker_base_docker_service_name] if devture_systemd_docker_base_docker_service_name else [] }}"
livekit_server_systemd_required_services_list_auto: []
livekit_server_systemd_required_services_list_custom: []
# Specifies the value of the `X-XSS-Protection` header # Specifies the value of the `X-XSS-Protection` header
# Stops pages from loading when they detect reflected cross-site scripting (XSS) attacks. # Stops pages from loading when they detect reflected cross-site scripting (XSS) attacks.

View File

@ -32,11 +32,43 @@
- name: Ensure LiveKit Server container image is pulled - name: Ensure LiveKit Server container image is pulled
community.docker.docker_image: community.docker.docker_image:
name: "{{ livekit_server_container_image }}" name: "{{ livekit_server_container_image }}"
source: pull source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
register: livekit_image_result force_source: "{{ livekit_server_container_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else livekit_server_container_image_force_pull }}"
when: "not livekit_server_container_image_self_build | bool"
register: result
retries: "{{ devture_playbook_help_container_retries_count }}" retries: "{{ devture_playbook_help_container_retries_count }}"
delay: "{{ devture_playbook_help_container_retries_delay }}" delay: "{{ devture_playbook_help_container_retries_delay }}"
until: livekit_image_result is not failed until: result is not failed
- when: "livekit_server_container_image_self_build | bool"
block:
- name: Ensure LiveKit Server repository is present on self-build
ansible.builtin.git:
repo: "{{ livekit_server_container_repo }}"
version: "{{ livekit_server_container_repo_version }}"
dest: "{{ livekit_server_container_src_files_path }}"
force: "yes"
become: true
become_user: "{{ matrix_user_username }}"
register: livekit_server_git_pull_results
- name: Ensure LiveKit Server container image is built
community.docker.docker_image:
name: "{{ livekit_server_container_image }}"
source: build
force_source: "{{ livekit_server_git_pull_results.changed if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else livekit_server_git_pull_results.changed }}"
build:
dockerfile: Dockerfile
path: "{{ livekit_server_container_src_files_path }}"
pull: true
- name: Ensure LiveKit Server container network is created
community.general.docker_network:
enable_ipv6: "{{ devture_systemd_docker_base_ipv6_enabled }}"
name: "{{ livekit_server_container_network }}"
driver: bridge
- name: Ensure LiveKit Server systemd service is installed - name: Ensure LiveKit Server systemd service is installed
ansible.builtin.template: ansible.builtin.template:

View File

@ -1,43 +1,47 @@
{% if livekit_server_container_labels_traefik_enabled %} {% if livekit_server_container_labels_traefik_enabled %}
traefik.enable=true traefik.enable=true
# Network configuration for Traefik
{% if livekit_server_container_labels_traefik_docker_network %} {% if livekit_server_container_labels_traefik_docker_network %}
traefik.docker.network={{ livekit_server_container_labels_traefik_docker_network }} traefik.docker.network={{ livekit_server_container_labels_traefik_docker_network }}
{% endif %} {% endif %}
traefik.http.services.matrix-livekit-server.loadbalancer.server.port={{ livekit_server_config_port }} traefik.http.services.{{ livekit_server_identifier }}.loadbalancer.server.port={{ livekit_server_config_port }}
{% set middlewares = [] %} {% set middlewares = [] %}
{% if livekit_server_container_labels_traefik_path_prefix != '/' %} {% if livekit_server_container_labels_traefik_path_prefix != '/' %}
traefik.http.middlewares.matrix-livekit-server-slashless-redirect.redirectregex.regex=({{ livekit_server_container_labels_traefik_path_prefix | quote }})$ traefik.http.middlewares.{{ livekit_server_identifier }}-slashless-redirect.redirectregex.regex=({{ livekit_server_container_labels_traefik_path_prefix | quote }})$
traefik.http.middlewares.matrix-livekit-server-slashless-redirect.redirectregex.replacement=${1}/ traefik.http.middlewares.{{ livekit_server_identifier }}-slashless-redirect.redirectregex.replacement=${1}/
{% set middlewares = middlewares + ['matrix-livekit-server-slashless-redirect'] %} {% set middlewares = middlewares + [livekit_server_identifier + '-server-slashless-redirect'] %}
traefik.http.middlewares.matrix-livekit-server-strip-prefix.stripprefix.prefixes={{ livekit_server_container_labels_traefik_path_prefix }} traefik.http.middlewares.{{ livekit_server_identifier }}-strip-prefix.stripprefix.prefixes={{ livekit_server_container_labels_traefik_path_prefix }}
{% set middlewares = middlewares + ['matrix-livekit-server-strip-prefix'] %} {% set middlewares = middlewares + [livekit_server_identifier + '-strip-prefix'] %}
{% endif %} {% endif %}
{% if livekit_server_container_labels_traefik_additional_response_headers.keys() | length > 0 %} {% if livekit_server_container_labels_traefik_additional_response_headers.keys() | length > 0 %}
{% for name, value in livekit_server_container_labels_traefik_additional_response_headers.items() %} {% for name, value in livekit_server_container_labels_traefik_additional_response_headers.items() %}
traefik.http.middlewares.matrix-livekit-server-add-headers.headers.customresponseheaders.{{ name }}={{ value }} traefik.http.middlewares.{{ livekit_server_identifier }}-add-headers.headers.customresponseheaders.{{ name }}={{ value }}
{% endfor %} {% endfor %}
{% set middlewares = middlewares + ['matrix-livekit-server-add-headers'] %} {% set middlewares = middlewares + [livekit_server_identifier + '-add-headers'] %}
{% endif %} {% endif %}
traefik.http.routers.matrix-livekit-server.rule={{ livekit_server_container_labels_traefik_rule }} traefik.http.routers.{{ livekit_server_identifier }}.rule={{ livekit_server_container_labels_traefik_rule }}
{% if livekit_server_container_labels_traefik_priority | int > 0 %} {% if livekit_server_container_labels_traefik_priority | int > 0 %}
traefik.http.routers.matrix-livekit-server.priority={{ livekit_server_container_labels_traefik_priority }} traefik.http.routers.{{ livekit_server_identifier }}.priority={{ livekit_server_container_labels_traefik_priority }}
{% endif %} {% endif %}
traefik.http.routers.matrix-livekit-server.service=matrix-livekit-server
traefik.http.routers.{{ livekit_server_identifier }}.service={{ livekit_server_identifier }}
{% if middlewares | length > 0 %} {% if middlewares | length > 0 %}
traefik.http.routers.matrix-livekit-server.middlewares={{ middlewares | join(',') }} traefik.http.routers.{{ livekit_server_identifier }}.middlewares={{ middlewares | join(',') }}
{% endif %} {% endif %}
traefik.http.routers.matrix-livekit-server.entrypoints={{ livekit_server_container_labels_traefik_entrypoints }}
traefik.http.routers.matrix-livekit-server.tls={{ livekit_server_container_labels_traefik_tls | to_json }} traefik.http.routers.{{ livekit_server_identifier }}.entrypoints={{ livekit_server_container_labels_traefik_entrypoints }}
traefik.http.routers.{{ livekit_server_identifier }}.tls={{ livekit_server_container_labels_traefik_tls | to_json }}
{% if livekit_server_container_labels_traefik_tls %} {% if livekit_server_container_labels_traefik_tls %}
traefik.http.routers.matrix-livekit-server.tls.certResolver={{ livekit_server_container_labels_traefik_tls_certResolver }} traefik.http.routers.{{ livekit_server_identifier }}.tls.certResolver={{ livekit_server_container_labels_traefik_tls_certResolver }}
{% endif %} {% endif %}
{% endif %} {% endif %}

View File

@ -1,8 +1,10 @@
#jinja2: lstrip_blocks: "True" #jinja2: lstrip_blocks: "True"
[Unit] [Unit]
Description=LiveKit Server Description=LiveKit Server
After=docker.service {% for service in livekit_server_systemd_required_services_list %}
Requires=docker.service After={{ service }}
Requires={{ service }}
{% endfor %}
[Service] [Service]
Type=simple Type=simple

View File

@ -1 +1,3 @@
livekit_server_public_url: "{{ livekit_server_scheme }}://{{ livekit_server_hostname }}{{ livekit_server_path_prefix }}" livekit_server_public_url: "{{ livekit_server_scheme }}://{{ livekit_server_hostname }}{{ livekit_server_path_prefix }}"
livekit_server_websocket_container_url: "ws://{{ livekit_server_identifier }}:{{ livekit_server_config_port}}"

View File

@ -49,6 +49,8 @@
- galaxy/redis - galaxy/redis
- galaxy/keydb - galaxy/keydb
- galaxy/valkey
- role: custom/matrix-authentication-service - role: custom/matrix-authentication-service
- custom/matrix-corporal - custom/matrix-corporal
- custom/matrix-appservice-draupnir-for-all - custom/matrix-appservice-draupnir-for-all
@ -133,7 +135,7 @@
- custom/matrix-pantalaimon - custom/matrix-pantalaimon
- custom/matrix-element-call - custom/matrix-element-call
- custom/matrix-livekit-server - custom/matrix-livekit-server
- custom/matrix-jwt-service - custom/matrix-livekit-jwt-service
- role: galaxy/postgres_backup - role: galaxy/postgres_backup