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

> Easily deploy OpenMAIC with the video export profile. Follow our complete setup guide to enable video export and activate the render service using Docker Compose.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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.

```bash
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.

```bash
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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

# .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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

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

```

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

```bash
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:

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

```

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

```json
{"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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts) and [`docker-compose.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.