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:

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 and contains settings used only at installation time.

Take a look at 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 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 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:

./generate_config.sh

To use a custom version, run:

./generate_config.sh <version>

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 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 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://<hostname> 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:
  • 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 and jibri.yaml 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, then
2. disable DEPLOY_SET_PUBLIC_IP in 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: https://github.com/flatcar/Flatcar/discussions/categories/flatcar-office-hours
  • Dev Sync: https://github.com/flatcar/Flatcar/discussions/categories/flatcar-developer-sync
  • Other community events like the "Maintenance Mode" bug-smashing day: https://github.com/flatcar/Flatcar/discussions/categories/community-events

• 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 <what>, 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.