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

> Easily set up OpenMAIC locally with Docker Compose. Clone the repo, configure your environment, and run a single command to get the web service up and running. Full guide available.

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

---

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

```bash
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/docker-compose.yml) file loads automatically.

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

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

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

```bash
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/docker-compose.yml) file. For advanced resource tuning options, refer to the [`render-service/README.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/render-service/README.md) file.

## Understanding the Docker Compose Architecture

### Service Definitions in [`docker-compose.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/docker-compose.yml)

The [`docker-compose.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

```bash
docker compose down --volumes

```

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

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