Unisphere - kaltura rtc

Overview

This repository is a Unisphere workspace for an experience named rtc.

It contains everything you need to:

• Create and publish npm / JFrog packages
• Bundle and version runtime artifacts
• Build and deploy applications
• Develop locally and promote changes to production

The Unisphere workspace acts as the single entry point for the entire lifecycle — from local development, through CI/CD, and all the way to production deployment.

To better understand the ideas behind Unisphere and how it works, read more at:
https://unisphere.kaltura.com/

Prerequisites

At the moment, deploying Unisphere experiences is available only to Kaltura employees.

Before doing anything else, make sure your machine is properly configured to access:

• Kaltura GitHub repositories
• Kaltura JFrog Artifactory registries

Follow the setup guide here:
https://unisphere.kaltura.com/docs/create/kaltura-employees/setup-machine

Add the Experience to Kaltura Github Organization

Before you can deploy or activate this experience, it must be registered in Github under Kaltura Organization.

This step connects your Unisphere workspace to the relevant Kaltura infrastructure and enables CI/CD, deployment, and activation flows.

Follow the guide here:
https://unisphere.kaltura.com/docs/create/devops/create-github-repository

Create Artifacts

Unisphere allows you to create and manage different types of artifacts, including:

• Packages
• Runtimes
• Applications

Each artifact type has its own role in the ecosystem, but they all live and evolve together inside this workspace.

Read more about creating artifacts here:
https://unisphere.kaltura.com/docs/create/overview

Deploy

To deploy packages, applications, and runtimes, follow the deployment guide:
https://unisphere.kaltura.com/docs/create/devops/deploy

For applications and runtimes, deployment is only part of the process.
After deployment, they must also be activated to become available in production.

Activation guide:
https://unisphere.kaltura.com/docs/create/devops/activate

Local Development

Unisphere provides a structured local development flow that mirrors production as closely as possible, while still keeping things fast and developer-friendly.

This includes:

• Local builds
• Watching and rebuilding artifacts
• Running applications in isolation or as part of a larger workspace

Read more about local development here:
https://unisphere.kaltura.com/docs/create/local-development

Available Commands

This workspace exposes a small set of opinionated commands to help you explore, validate, and manage the experience.

Start

Lists all available commands for each artifact in the experience, including how to build and serve runtimes, and how to spawn applications.

npm run start

Info

Displays information about the current workspace, including detected artifacts, configuration, and environment details.

npm run info

Check

Validates the workspace setup and verifies that all required artifacts and configurations are in place.

npm run check

Reset

Resets the workspace to a clean state. Useful when experimenting or when local state becomes inconsistent.

npm run reset

Releasing

This project uses Changesets for versioning and publishing. The CI/CD pipeline handles version bumping and publishing automatically — you only need to create the changeset and push.

Before Any Release

Always verify lint passes before starting any release flow:

./node_modules/.bin/nx run unisphere-package-avatar:lint --fix --verbose

Fix any errors before proceeding.

Stable Release (merging to main)

1. On your feature branch, create a changeset describing what changed:

   npm run changeset

   Follow the prompts — select the packages changed and the bump type (patch / minor / major).

2. Commit and push the generated .changeset/<name>.md file along with your code changes.

3. Open a PR to main. The PR checks run tests automatically.

4. Once merged to main, CI automatically creates a "Version Packages" PR (changeset-release/main → main) that contains the bumped versions and updated changelogs.

5. Merge the "Version Packages" PR — CI then publishes the packages to the registry.

Prerelease

Prereleases publish tagged versions (e.g., 1.30.0-stv-webrtc.0) without touching main.

Critical: The branch name MUST start with prerelease/ — CI only triggers on prerelease/** branches.

Step-by-step

1. Create and push a prerelease/<tag> branch from your feature branch:

   git checkout -b prerelease/my-feature
   git push -u origin prerelease/my-feature

   The <tag> (e.g., my-feature) becomes the prerelease identifier in the version number.

2. Enter prerelease mode — run this while on the prerelease branch:

   npx changeset pre enter my-feature

   This creates .changeset/pre.json. The tag must match the suffix of your branch name.

3. Create a changeset for your changes:

   npm run changeset

4. Commit and push both files:

   git add .changeset/
   git commit -m "chore: enter prerelease mode for my-feature"
   git push

5. CI creates a "Version Packages" PR (changeset-release/prerelease/my-feature → prerelease/my-feature). Merge it to publish the prerelease.

6. Subsequent changes on the same branch: just add new changesets (npm run changeset) and push. Each push triggers a new prerelease version bump.

Finishing a prerelease

When the feature is ready for a stable release, exit prerelease mode on the branch:

npx changeset pre exit
git add .changeset/pre.json
git commit -m "chore: exit prerelease mode"
git push

Then merge the branch (or its changesets) into main for the stable release flow.

Undoing a Botched Prerelease

If the prerelease setup gets into a broken state, reset to the last clean commit and force-push:

# Find the last commit before any changeset work
git log --oneline

# Reset to that commit (replace <sha> with the actual hash)
git reset --hard <sha>
git push --force origin prerelease/my-feature

Then start the prerelease setup again from step 2 above.

Next Steps

If this is your first time working with Unisphere, a great next step is to create a runtime with a playground.

Follow the Hello World walkthrough here: https://unisphere.kaltura.com/docs/create/overview

The walkthrough will guide you through:

• Creating your first runtime
• Running it locally with a playground
• Understanding how runtimes, packages, and applications connect together

This will give you a strong foundation for building and evolving the experience over time.