Skip to main content

Set Up a Project

You create your own project from the Mosaic Media Template, an open-source starting point for building video and OTT solutions. It contains the customizable services as source code, together with everything you need to develop, build, and deploy them. You can use the services as they are or adapt them to your needs.

What the Media Template Contains​

  • Media Service - Manage the metadata of your movies and TV shows and orchestrate their ingest.
  • Catalog Service - Deliver your published catalog, such as movies, TV shows, seasons and genres, to your frontend apps.
  • Entitlement Service - Control which content each subscriber can access and what rules apply for playback.
  • Channel Service - Curate channels and playlists.
  • VOD-to-Live Service - An example that publishes the channels of the Channel Service as live streams.
tip

Not ready to code yet? Try the services first: deploy them to your Mosaic environment and explore them using the UI and APIs.

Create Your Project​

Setting up a project takes five steps: check the tools, get the template, set up a development environment, prepare the solution, and run it. This page explains what each step does and in which order to take them. The README.md in your project contains the exact commands for your version of the template, as they can change with each release. The README links on this page point to the latest version on GitHub.

Before You Begin​

Make sure the following tools are installed on your machine:

  • Git manages the source code of your project.
  • Node.js runs the services.
  • Yarn installs the dependencies and runs the project scripts.
  • Docker runs the local database.
  • Visual Studio Code (recommended) is the editor the template is set up for.

For the required versions and notes for Windows, Linux, and macOS, see the prerequisites in the README.

Get the Template​

Choose how you want to get the Mosaic Media Template:

Run the following command in your terminal:

npx -p @axinom/mosaic-cli@latest mosaic create

The command asks you the following questions:

  • Project name: the name of your project.
  • Target folder: the folder to create the project in.
  • Installation type: choose Stable to get the latest released version of the template.
  • Initialize a git repository?: keep the default, Yes.
  • Install dependencies?: keep the default, Yes.

For all options of the command, see the Mosaic CLI documentation.

Open the project folder in Visual Studio Code, and install the recommended extensions when you're asked to.

Set Up a Development Environment​

The services in your project run on your machine, but they connect to a Mosaic environment in the cloud. The environment provides the core services, such as the Identity Service and the message bus.

tip

You need an Axinom Portal account to set up an environment. If you don't have one yet, start a free trial to create one for free.

  1. Choose an environment of the type Development. You can use the environment that your free trial created, or create a new one in Axinom Portal. See Environment Management for details.
  2. Open the Environment Connection page of the environment. It's available in the Admin Portal, from the details of your environment. The page creates the connection values for your local project: the IDs of your tenant and environment, the message bus credentials, and a development service account.
  3. Click Copy to Clipboard or Download to save the connection values. You paste them into the .env file in step 5 of Prepare the Solution, so keep them until then.
caution

The Environment Connection page shows the secrets only once. If you lose them, you can create new connection values on the same page, but this replaces the old ones, and you have to update every project that uses them.

Prepare the Solution​

Follow the README section Prepare and connect the media-template solution. It takes you through the following steps:

  1. Install the dependencies. If you used the Mosaic CLI and let it install the dependencies, this step is already done.
  2. Create the local configuration files, such as .env, from the templates included in the solution.
  3. Start the local development infrastructure, a PostgreSQL database and pgAdmin, in Docker.
  4. Create the databases for all services.
  5. Paste the connection values from the Environment Connection page into the .env file in the root folder.
  6. Run the setup, which connects the services to your environment. For example, it creates a service account for each service and adds its credentials to the .env files.

Run the Solution​

Follow the README section Run the solution. You start three processes in watch mode, each in its own terminal:

  1. The shared libraries. Wait until they finish compiling before you start the other two.
  2. The backend services: Media, Catalog, and Entitlement.
  3. The Management System workflows of the Media Service.

Then open http://localhost:10053 in your browser and sign in with a user of your environment. Your setup works if you see the Management System with tiles such as Movies, TV Shows, and Episodes.

The Channel and VOD-to-Live services are not started by default; see the note under Solution Structure.

Next Steps​

Solution Structure​

The Mosaic Media Template is a monorepo. Its structure is optimized for the suggested tools, such as Visual Studio Code, ESLint, Prettier, and Vitest.

Root Level​

  • README.md contains the setup instructions.
  • package.json contains the scripts to build, run, and test the services.
  • The configuration files set up the editor, ESLint, Prettier, Vitest, Git, Yarn, Docker, and the environment variables. They contain the Mosaic defaults, which you can adjust to your preferences.
  • .vscode contains the suggested settings and extensions for Visual Studio Code, and code snippets for writing SQL migrations.
  • infra contains a Docker Compose file to set up the local development resources.
  • scripts contains helper scripts, for example to deploy a service or to set up hosting.
  • CLAUDE.md and .claude give AI coding agents context and skills for working in the solution. See Develop with AI for more.
  • .github, .adops, and .kubernetes contain the build and deployment pipelines that Axinom uses for the template. You can reuse the build pipelines for your project. The deployment pipelines target Axinom's own environments, so use them as an inspiration for your own.

Libraries and Services​

  • libs contains the shared libraries. The media-messages library defines the JSON schemas of the messages that the services send through the message bus.
  • services contains one folder per service. Each has a service folder with the backend; services that integrate into the Management System also have a workflows folder with their frontend.
FolderBackend (service)Management System UI (workflows)
mediaYesYes
catalogYesNo
entitlementYesNo
channelYesYes
vod-to-liveYesNo

The Catalog and Entitlement services have no workflows because they are used by your end-user apps rather than by editors. vod-to-live contains the VOD-to-Live example of the Channel Service.

Each service folder has its own .env.template for service-specific settings, a migrations folder with the database migrations, and a mosaic-hosting-deployment-manifest.yaml for deploying the service with the Hosting Service.

note

The Channel and VOD-to-Live services are not part of the default build and development scripts. To include them, use the :all variants of the scripts, such as build:all or dev:services:all.

Tests​

Test files are suffixed with .spec.ts and are usually located next to the tested logic. For tests of database-specific logic, use the suffix .db.spec.ts. This creates an independent database for every test file, so tests running in parallel don't affect each other.

See also​

Was this page helpful?