How to Deploy OpenMAIC with the Video Export Profile: Complete Setup Guide

Deploy OpenMAIC with the video export profile by enabling the NEXT_PUBLIC_ENABLE_VIDEO_EXPORT environment flag and launching Docker Compose with the --profile video-export flag to activate the isolated render service.

OpenMAIC (THU-MAIC/OpenMAIC) is an open-source AI classroom platform that supports exporting interactive sessions as MP4 video files through an optional containerized rendering pipeline. To deploy OpenMAIC with the video export profile, you must configure a specific feature flag and launch an isolated render service that handles video generation using Chromium and FFmpeg. This guide walks through the exact commands, configuration files, and architecture required to enable one-click video downloads in your self-hosted instance.

Prerequisites

Before starting, ensure your system meets the following requirements:

• Docker Engine and Docker Compose installed (version supporting Compose profiles)
• 8 GB of available RAM minimum for the render service container (MP4 rendering is memory-intensive)
• pnpm installed locally if you plan to run development commands outside containers

Step-by-Step Deployment

Clone the Repository and Install Dependencies

Start by cloning the OpenMAIC repository and installing the JavaScript dependencies. This provides the baseline configuration including the Docker Compose definitions and example environment files.

git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
pnpm install

Copy the example environment file to create your local configuration. This file controls feature gates and API keys.

cp .env.example .env.local

Enable the Video Export Feature Flag

The video export functionality is gated by the NEXT_PUBLIC_ENABLE_VIDEO_EXPORT environment variable. According to the source code in lib/config/feature-flags.ts, the function isVideoExportEnabled() reads this variable to determine UI visibility (lines 16-23).

Edit .env.local to enable the feature:

# .env.local

NEXT_PUBLIC_ENABLE_VIDEO_EXPORT=true
OPENAI_API_KEY=sk-...

Important: Because this is a NEXT_PUBLIC_ variable, it must be set at build time. The Docker Compose configuration passes this variable as a build argument, which the Next.js application consumes during the image build process (as documented in packages/docs/content/docs/deployment.mdx, lines 36-42).

Launch Docker Compose with the Video-Export Profile

The video-export profile is defined in docker-compose.yml (lines 66-82) and adds the render-service container to the stack. This container runs Chromium and FFmpeg in an isolated environment to convert classroom Hyperframes into MP4 files.

Run the following command to build and start the application with video export capabilities:

docker compose --profile video-export up --build

To combine video export with server-side persistence, include both profiles:

NEXT_PUBLIC_PERSISTENCE=1 \
NEXT_PUBLIC_PERSISTENCE_TOKEN=openmaic-local-dev \
docker compose --profile server-persistence --profile video-export up --build

Verify the Render Service Connection

Once the containers are running, verify that the application can reach the render service. The application probes the RENDER_SERVICE_URL (defaulting to http://render-service:9000) to check availability.

Test the service health directly:

curl -s http://localhost:9000/health | jq .

The expected response confirms the service is ready to accept rendering jobs:

{"status":"ok"}

If the render service is unreachable, the UI gracefully degrades to offering a ZIP file export instead of MP4 video.

Architecture Overview

Understanding how the components interact helps with troubleshooting and resource planning.

The Render Service Container

The docker-compose.yml file defines the video-export profile that conditionally includes the render-service container. This service encapsulates a headless Chromium browser and FFmpeg toolchain, keeping the heavy rendering dependencies isolated from the main application container.

Feature Flag Implementation

In lib/config/feature-flags.ts, the isVideoExportEnabled() function checks for the NEXT_PUBLIC_ENABLE_VIDEO_EXPORT environment variable. When this returns true, the React frontend exposes the "Export Video" button in the classroom UI. Without this flag, the button remains hidden to prevent user confusion in environments lacking rendering capabilities.

Export Flow

When a user clicks "Export Video":

1. The frontend streams the Hyperframes project data to the render-service at the configured URL
2. The render service loads the session in a headless Chromium instance and captures video frames
3. FFmpeg encodes the frames into an MP4 container
4. The file streams back to the user for download

Advanced Configuration

Resource Limits for Rendering

MP4 rendering consumes significant memory and CPU. If you experience container crashes during export, increase the memory limits in your Docker Compose override file. The default configuration assumes an 8 GB system, but production deployments handling complex classroom sessions may require 12-16 GB allocated to the render service.

Environment Variable Reference

Variable	Location	Purpose
NEXT_PUBLIC_ENABLE_VIDEO_EXPORT	.env.local	Build-time flag enabling the export UI
RENDER_SERVICE_URL	Environment	URL to the render service (default: http://render-service:9000)

Summary

• Enable the feature flag by setting NEXT_PUBLIC_ENABLE_VIDEO_EXPORT=true in .env.local before building the Docker image.
• Use the profile flag --profile video-export when running docker compose up to include the Chromium-based render service.
• Verify connectivity by checking that the application can reach http://render-service:9000 (or your custom RENDER_SERVICE_URL).
• Monitor resources because MP4 generation is memory-intensive; ensure the render service container has at least 8 GB RAM.
• Reference the source in lib/config/feature-flags.ts and docker-compose.yml for internal logic and service definitions.

Frequently Asked Questions

What is the default URL for the render service?

The default URL is http://render-service:9000, configured via the RENDER_SERVICE_URL environment variable. If you modify the service name or port in docker-compose.yml, you must update this URL to match your network configuration.

Why is the "Export Video" button not appearing in the UI?

The button is gated by the isVideoExportEnabled() function in lib/config/feature-flags.ts. Ensure NEXT_PUBLIC_ENABLE_VIDEO_EXPORT is set to true in .env.local before building the Docker image, as Next.js bakes this value into the client bundle at build time. Changing the variable in a running container without rebuilding will not reveal the button.

What happens if the render service becomes unavailable?

If the application cannot reach the RENDER_SERVICE_URL endpoint, the export functionality gracefully degrades. Instead of generating an MP4, the system offers users a ZIP archive containing the session data, ensuring classroom exports remain functional even when the video rendering pipeline is offline.

Can I run the video export service without Docker?

While technically possible, running the render service without Docker is not recommended. The service requires a specific Chromium build with proprietary codecs and a compatible FFmpeg installation. The provided video-export Docker profile handles these complex dependencies automatically; manual installation requires matching the exact versions specified in the render-service Dockerfile.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}