How to Set Up OpenMAIC Locally Using Docker Compose: A Complete Guide

You can set up OpenMAIC locally by cloning the THU-MAIC/OpenMAIC repository, copying .env.example to .env.local, and running docker compose up --build to start the web service on localhost:3000, with optional PostgreSQL persistence and video-export services available via Docker Compose profiles.

OpenMAIC is an open-source platform delivered as a set of containerized services defined in the repository's docker-compose.yml file. Whether you are developing new features or deploying a local instance for testing, using Docker Compose provides a reproducible environment with configurable persistence and rendering capabilities.

Prerequisites

Before you begin the setup process, ensure your system meets the following requirements:

• Docker ≥ 20.10 – Provides the container runtime required to build and run the images.
• Docker Compose – Must support the v2 syntax used throughout the docker-compose.yml configuration.
• Git – Optional but recommended for cloning the repository directly from GitHub.

Step-by-Step Setup Guide

Clone the Repository

First, obtain the source code from the THU-MAIC/OpenMAIC repository and navigate into the project directory.

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

Configure Environment Variables

The project relies on environment variables for runtime configuration. The repository includes an example file that you must copy to .env.local, which the docker-compose.yml file loads automatically.

cp .env.example .env.local

Edit .env.local to override any build-time or runtime variables, such as ALPINE_MIRROR for faster image builds or NEXT_PUBLIC_PERSISTENCE to enable database storage features. For production deployments, ensure you modify default credentials like POSTGRES_PASSWORD.

Start the Core OpenMAIC Service

To launch the primary web application, execute the build command. This compiles the openmaic service and exposes port 3000.

docker compose up --build

Once the containers start, access the application at http://localhost:3000. The service runs in the foreground by default; add the -d flag to run detached.

Enable PostgreSQL Persistence (Optional)

If you require data persistence beyond container lifecycles, enable the server-persistence profile. This starts a PostgreSQL 16 container connected to the openmaic-postgres volume.

docker compose --profile server-persistence up -d

The compose file sets default credentials (POSTGRES_USER=openmaic, POSTGRES_PASSWORD=openmaic-dev) inside the container. Update these values in .env.local before running this command in production environments. The application connects via the DATABASE_URL variable defined in your environment configuration.

Enable MP4 Video Export (Optional)

The video export functionality requires a heavyweight renderer using Chromium and FFmpeg. Because this service introduces significant resource overhead, it is isolated behind the video-export profile.

docker compose --profile video-export up -d

This command builds the render-service from the ./render-service directory and attaches it to the isolated render network. The main application automatically discovers the renderer at http://render-service:9000 as configured in the environment block of the docker-compose.yml file. For advanced resource tuning options, refer to the render-service/README.md file.

Understanding the Docker Compose Architecture

Service Definitions in docker-compose.yml

The docker-compose.yml file at the repository root defines three primary services:

• openmaic – The core Next.js web application exposing port 3000.
• postgres – PostgreSQL 16 database for persistent storage, activated via the server-persistence profile.
• render-service – Chromium/FFmpeg renderer for MP4 export, activated via the video-export profile.

Network Isolation and Security

OpenMAIC implements a dual-network strategy for security:

• default network – Provides outbound Internet access to the openmaic container for LLM APIs and external media providers.
• render network – An isolated internal network connecting only the openmaic and render-service containers. This prevents the heavyweight renderer from accessing external networks, reducing the attack surface.

Persistent Storage Volumes

Data persistence is handled through Docker volumes defined in the compose file:

• openmaic-data – Stores application files and generated assets.
• openmaic-postgres – Stores database files when the persistence profile is active.

These volumes survive container restarts unless you explicitly remove them with docker compose down --volumes.

Verification and Testing

After starting the services, verify your deployment:

1. Open http://localhost:3000 in a browser to confirm the OpenMAIC UI loads.
2. If running the render service, check the health endpoint at http://localhost:9000/health for a 200 OK response.
3. If PostgreSQL is enabled, connect using any SQL client with the credentials specified in .env.local.

To stop the entire stack and remove associated volumes (which deletes persistent data), run:

docker compose down --volumes

For a quick development setup with all optional features enabled, use this one-liner:

git clone https://github.com/THU-MAIC/OpenMAIC.git && cd OpenMAIC && \
cp .env.example .env.local && \
docker compose --profile video-export up -d --build

Summary

• Core setup requires only docker compose up --build after cloning the repository and creating .env.local from .env.example.
• Optional profiles extend functionality: use --profile server-persistence for PostgreSQL storage and --profile video-export for MP4 rendering capabilities.
• Network isolation keeps the render service secure via the internal render network, while the default network allows external API access.
• Data persistence relies on Docker volumes openmaic-data and openmaic-postgres, which remain intact across container restarts unless manually purged.

Frequently Asked Questions

What are the minimum system requirements for running OpenMAIC locally?

You need Docker version 20.10 or higher with Docker Compose v2 syntax support. The core web service runs comfortably on modest hardware, but enabling the video-export profile requires substantial resources due to Chromium and FFmpeg operations. For specific resource limits and tuning parameters for the renderer, consult the render-service/README.md file.

How do I persist data between container restarts?

Start the stack with the server-persistence profile using docker compose --profile server-persistence up -d. This activates the PostgreSQL service and mounts the openmaic-postgres volume. Avoid using docker compose down --volumes unless you intend to wipe all stored data, as that flag removes the volumes.

Can I run OpenMAIC without the video export feature?

Yes, the video export service is entirely optional. Omit the --profile video-export flag when starting the containers, and the application will run without the Chromium renderer. The core functionality at localhost:3000 operates independently of the render-service.

How do I stop and clean up the OpenMAIC Docker containers?

Run docker compose down to stop and remove the running containers. Add the --volumes flag to delete the persistent data in openmaic-data and openmaic-postgres volumes. If you used specific profiles to start the services, include those same profiles in the down command to ensure all associated containers are properly terminated.

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