https://github.com/flatcar/flatcar-app-jitsi
Automation for the Flatcar Jitsi server
https://github.com/flatcar/flatcar-app-jitsi
Last synced: 2 months ago
JSON representation
Automation for the Flatcar Jitsi server
- Host: GitHub
- URL: https://github.com/flatcar/flatcar-app-jitsi
- Owner: flatcar
- License: apache-2.0
- Created: 2022-09-15T15:27:19.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-11-12T15:03:55.000Z (7 months ago)
- Last Synced: 2025-11-12T17:11:44.885Z (7 months ago)
- Language: Shell
- Size: 366 KB
- Stars: 1
- Watchers: 8
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
[](https://app.element.io/#/room/#flatcar:matrix.org)
[](https://kubernetes.slack.com/archives/C03GQ8B5XNJ)
[](https://x.com/flatcar)
[](https://hachyderm.io/@flatcar)
[](https://bsky.app/profile/flatcar.org)
# Jitsi as a Flatcar App.
This repo contains automation for deploying a full-featured Jitsi server on demand, within seconds.
The automation uses docker-compose files from https://github.com/jitsi/docker-jitsi-meet.
# Features
- A full-featured Jitsi server, stateless, deploy when you need it (and remove it afterwards)
- Jibri integration for server-side recording and live streaming
- LetsEncrypt integration for serving HTTPS from your Jitsi host
- Very minimal configuration requirements:
- A host to provision Flatcar to with the `ignition.json` generated from this repo
- hostname DNS entry and email address (for LetsEncrypt HTTPS cert)
- Provisioning can be tested in a local qemu VM.
# Installation
Although this installation is Flatcar branded you might re-use this repo to deploy your own Jitsi server.
Branding is patched in at configuration build time; just skip this step (in `generate_config.sh`)
and you'll get a stock Jitsi server.
You can also use your own logos, banner, and watermark.
The installation will go through these steps
- Clone this repo locally and configure your new server with minimal settings
- build your Flatcar ignition Jitsi configuration
- Provision a new Flatcar machine / VM and pass the ignition configuration (via "user data")
- Connect to your Jitsi server and meet away!
## Configure your deployment
First, clone this repo locally:
```bash
git clone https://github.com/flatcar/jitsi-server.git
cd jitsi-server
```
The deployment can be customised on 2 separate levels:
* `jitsi-config.env` is used by the script that generates our deployment configuration.
It holds mandatory and optional settings (see below) for generating and tailoring the deployment.
Also, important runtime environment variables for the Jitsi containers are set here.
* `jitsi-install.env` is used by the on-node Jitsi installer script [`jitsi-install.sh`](jitsi-install.sh)
and contains settings used only at installation time.
Take a look at [`jitsi-config.env`](jitsi-config.env) and set
- `JITSI_SERVER_FQDN` to your new server's designated DNS name.
You will need to point the respective DNS record to your new Jitsi server later,
before or during provisioning.
- `LETSENCRYPT_EMAIL` to your email address for receiving LetsEncrypt notifications.
This is particularly important for long-running servers as LetsEncrypt will send
TLS certificate expiries to that email address.
To refresh a certificate simply restart the Jitsi service (or the whole node).
You'll also find a number of pre-set variables for customising Jitsi features, e.g. authentication.
You may (but are not required to) change installer settings, too.
Check out [`jitsi-install.env`](jitsi-install.env) next:
* If you've set `ENABLE_AUTH` in `jitsi-config.env`, you may want to set a moderator username here.
* Optionally you can also set a moderator password.
A random password will be generated otherwise, and you need to retrieve it from the instance's
`/opt/jitsi/.env` file once it is provisioned.
The file also contains DNS/IP related options important to the installation process.
That's it, you're good to go!
## Generate configuration and deploy
This step will fetch docker compose YAML files from
[docker-jitsi-meet](https://github.com/jitsi/docker-jitsi-meet)
for a specific Jitsi release, and generate a self-contained configuration to pass
into a Flatcar deployment.
The config generator requires a Jitsi version.
At the time of writing, `stable-`10590` was the latest release.
This version is the default.
To use this version, run:
```bash
./generate_config.sh
```
To use a custom version, run:
```bash
./generate_config.sh
```
For a full list of Jitsi releases, check out
https://github.com/jitsi/docker-jitsi-meet/releases.
This generates `ignition.json` which we'll feed into the Flatcar deployment.
Optionally pass `--no-branding` to `./generate_config.sh` to disable branding.
If your target deployment is ARM64, pass `--arch arm64` to
`./generate_config.sh` so the correct docker sysexts are used.
## Deploy
Deploy a new Flatcar instance on a
[cloud provider or private cloud of your choice](https://www.flatcar.org/docs/latest/installing/cloud/)
and feed `ignition.json` to the deployment.
If you deploy to a locked-down environment e.g. behind a NAT or firewall, make
sure to open ports 80 and 443 (TCP) and 10000 (UDP) to the instance (and
optionally port 22 if you want to ssh into your server).
The deployment is zero-touch.
There should be no need to interact with the instance to aid the deployment.
As soon as you know the IP address of your Flatcar Jitsi host, point the hostname DNS entry
(the one we used for `JITSI_SERVER_FQDN`) to that IP.
At first boot, the [installer](jitsi-install.sh) will run and set up Jitsi in `/opt/jitsi`.
Jitsi will become available at the designated hostname after a few minutes.
## Meet
Connect to the host via `https://` and start a meeting.
By default, authentication is enabled - though unauthenticated guests can enter after
an authenticated host has started a meeting.
The default authenticated user name is `flatcar`, and the password is auto-generated on
the node during provisioning.
Initial user and password are appended to `/opt/jitsi/.env` on the server.
See Customisation below on how to pass a custom user/password into the deployment.
## Customisations
- Installer script settings can be overridden in [jitsi-install.env](jitsi-install.env):
- `MODERATOR_USER` Custom Jitsi meeting moderator user name
- `MODERATOR_PASS` Password for `MODERATOR_USER`.
Will be auto-generated at provisioning time and appended to `/opt/jitsi/.env` if not set.
- `DEPLOY_SET_PUBLIC_IP` When `true`, before installing Jitsi, determine the server's public IP
address and explicitly configure Jitsi for that IP address (via `JVB_ADVERTISE_IPS`).
This is handy for running in a NATed / load-balanced cloud environment where the
instance doesn't know its public IP address (e.g. in protected Azure environments).
Alternatively, this can be set to a public IP address to use _that_ address for the server.
_Set to empty or to `false` to disable._
- `DEPLOY_WAIT_FOR_HOSTNAME_DNS` wait for the hostname `JITSI_SERVER_FQDN` to resolve to
the host's public IP before installing Jitsi. Needs `DEPLOY_SET_PUBLIC_IP`.
In order to ensure we're not flooding LetsEncrypt with certificate queries (and get blocked as a result), the
installer will check whether the designated hostname matches its public IP address before
continuing the installation.
- Jitsi settings such as LetsEncrypt usage, authentication, live streaming and recording can be set in
`jitsi-config.env`. All env variables of jitsi-docker's
[`docker-compose.yml`](https://github.com/jitsi/docker-jitsi-meet/blob/master/docker-compose.yml)
and [`jibri.yaml`](https://github.com/jitsi/docker-jitsi-meet/blob/master/jibri.yml)
can be overridden there.
## Test the set-up locally
You can test locally in a qemu VM.
1. Uncomment the local test settings at the bottom of [`jitsi-config.env`](jitsi-config.env), then
2. disable `DEPLOY_SET_PUBLIC_IP` in [jitsi-install.env](jitsi-install.env), and
3. re-generate the configuration by running `./generate_config.sh`
Fetch the latest `flatcar_production_qemu_uefi_efi_code.fd`,
`flatcar_production_qemu_uefi_efi_vars.fd`,
`flatcar_production_qemu_uefi_image.img`,
`flatcar_production_qemu_uefi.sh` from https://stable.release.flatcar-linux.net/amd64-usr/current/ .
Start a local Flatcar instance, pass `ignition.json` and export the necessary ports:
```
chmod 755 flatcar_production_qemu_uefi.sh
./flatcar_production_qemu_uefi.sh -i ignition.json \
-p 4080-:4080,hostfwd=tcp::4443-:4443,hostfwd=udp::10000-:10000,hostfwd=tcp::2222 \
-m 4096
-nographic -snapshot
```
(Note that the `-snapshot` option runs the VM in ephemeral mode, i.e. all changes to the VM
will be discarded when it powers down.
This is useful for testing re-provisioning.)
# Operate Jitsi
The below runbook contains instructions for Flatcar maintainers for operating flatcar-app-jitsi on our infrastructure.
While the workflow might be useful for other projects, most items are specific to the Flatcar project.
## Pre-create the session
In this section, we'll check the Agenda "discussion" and update the youtube live stream.
We'll obtain:
- The title and summary for the meeting
- The live stream URL
Before starting the meeting, gather the necessary information:
- Open the upcoming meeting's agenda discussion on GitHub.
There should be only one open "discussion" (the latest) in the respective category.
**This step will provide title and meeting summary for later steps**.
- Office Hours:
- Dev Sync:
- Other community events like the "Maintenance Mode" bug-smashing day:
- Pre-create the youtube live stream / recording.
**This step will provide the youtube stream URL for later steps.**
- Go to https://www.youtube.com/
- Make sure you're the "Flatcar channel" user @FlatcarLinux (user avatar at the upper right)
- Click "+ Create" at the upper right, select "Go Live".
You will be directed to the Youtube Studio live streaming UI.
- Update the stream meta-information; most importantly, title and summary:
- Title follows the format `YYYY-MM-DD Flatcar `, e.g. for the 2025 October Office Hours it's `2025-10-08 Flatcar Office Hours`.
- Summary can be copy+pasted from the Agenda "discussion" on GitHub.
- After updating meta-information, click "share" (a curved arrow on the right, at the very top).
- Copy the video URL and *paste it into a new browser window*.
- After the window loaded (the stream will show as "live stream offline"), copy the URL from the address bar.
Best leave the Youtube streaming UI tab open. You'll need it later for the streaming key.
## Announce the meeting
We can now create announcement messages for Matrix and Slack, and update the Matrix channel's embedded youtube video.
Announcements usually happen briefly (1h to 30min) before the meeting starts.
- Open the Agenda "discussion" and edit the short summary at the top to add the youtube URL.
There should be a bullet point `-Youtube live stream / recording: TBD`, replace TBD with the actual youtube URL.
- Go to the "Flatcar" Matrix channel at https://app.element.io/?#/room/#flatcar.
- Open the "Room info" via the small circular "(i)" button at the top right.
- Select "Extensions".
- Click "+ Add extension" at the top right.
- In the dialog window, under "Added to this room", there should be the youtube extension. Click it.
- In order to update the URL, we need to remove and re-add it.
Select "Delete" to remove the youtube extension.
- This will bring you back to the main "Add extension" dialog.
Select the youtube widget which has now moved to "Widgets".
- Put in the youtube URL. There's no need to add a title as the title will be fetched from youtube. Click "Add".
- Close the "Add extensions" dialog.
- Back in the "Extensions" menu, the youtube widget will be listed.
Select "pin" via the little "pin" icon right of the youtube widget.
- Then click "Set layout for everyone" (text below the list of extensions".
- Still in the Matrix channel, write the announcement.
**Keep in mind to always press Shift+Return, never _just_ Return, as this will prematurely send the message.**
- On the first line, announce what meeting it is, when the meeting will start (time difference as well as absolute time).
You can use `@room` to ping everyone in the channel.
- Below that, copy+paste the intro paragraph from the Agenda, and the first 2 bullet points (Jitsi URL and youtube URL).
Add one bullet point with the Agenda URL
- You can use emoji and markdown formatting.
Leave empty lines between sections to improve readability.
Example announcement (Please make sure to change the links to yours! And not use the ones in this example):
```
@room 📢 **The Flatcar community office hours will commence in ~45min**, at 2:30pm UTC
In the office hours we discuss news and happenings in and around Flatcar, provide a space for our user community to discuss with maintainers, show demos, and do our release planning.
Join if you want to learn about the project and get in contact with other users and with maintainers.
- Agenda: https://github.com/flatcar/Flatcar/discussions/1900
- Jitsi: https://meet.flatcar.org/OfficeHours
- Youtube live stream / recording: https://www.youtube.com/live/43ITkUiRpU4
```
- Slack: we announce the meeting in both the "Kubernetes" and "CNCF" slack, in the respective `#flatcar` channel.
**Keep in mind to always press Shift+Return, never _just_ Return, as this will prematurely send the message.**
- You can copy+paste the _rendered_ (after sending) Matrix announcement (without `@room`); it will mostly keep its formatting (and emojis).
- Pinging whole channels is (sadly) disabled in both Slacks.
## Start the meeting and stream it to youtube
- Open the youtube streaming UI where we prepared the stream earlier.
- Start the meeting on Jitsi
- go to https://meet.flatcar.org/OfficeHours and start the meeting.
You'll need the Jitsi credentials to log in as a moderator.
- If the meeting already started, you can authenticate via:
- press the "..." button ("More action")
- select your user at the top of the the pull-up menu
- then select "Profile" (should already be selected
- click the "Log-in" button.
- After everyone joined, start the streaming / recording.
- Select "..." ("More actions") which will open a pull-up menu
- Click "Start live stream"
- In the Youtube streaming UI, click "copy streaming key".
**Be careful not to disclose the streaming key. Consider it a password.**
- Paste the youtube streaming key to the Jitsi live stream dialog, and start the stream.
## During the meeting
Check the youtube studio streaming UI every now and then.
People watching the live stream may use the chat for asking questions; the chat is visible on the youtube studio streaming UI.
## After the meeting
- To close the meeting, use "End meeting for all".
This will also stop the live stream.
- End the stream in Youtube studio.
- Check the Agenda: there are 2 TODO items at the very bottom:
- Create a new Agenda "discussion" for the next meeting.
- Close the Agenda discussion of the now completed meeting.