# How to Run Next AI Draw.io with Docker Compose: Complete Setup Guide

> Learn to run Next AI Draw.io with Docker Compose. This guide details setting up Draw.io UI on port 8080 and Next.js on port 3000 using docker-compose yml for a seamless workflow.

- Repository: [Dayuan Jiang/next-ai-draw-io](https://github.com/DayuanJiang/next-ai-draw-io)
- Tags: how-to-guide
- Published: 2026-07-13

---

**Run Next AI Draw.io with Docker Compose by orchestrating two containers—the Draw.io UI on port 8080 and the Next.js application on port 3000—using the provided [`docker-compose.yml`](https://github.com/DayuanJiang/next-ai-draw-io/blob/main/docker-compose.yml) file and an environment configuration file.**

Next AI Draw.io, available in the [DayuanJiang/next-ai-draw-io](https://github.com/DayuanJiang/next-ai-draw-io) repository, combines AI-powered diagram generation with the Draw.io interface. Deploying via Docker Compose eliminates Node.js dependency management and handles the multi-service architecture automatically.

## Understanding the Docker Compose Architecture

The [`docker-compose.yml`](https://github.com/DayuanJiang/next-ai-draw-io/blob/main/docker-compose.yml) file at the repository root defines two cooperating services. This separation allows independent scaling of the diagramming interface while maintaining tight integration between components.

### The Draw.io Service

The first service uses the official `jgraph/drawio:latest` image to render diagram XML. According to the configuration in [`docker-compose.yml`](https://github.com/DayuanJiang/next-ai-draw-io/blob/main/docker-compose.yml), this container exposes port **8080** and provides the embedded editor that the Next.js application references via `NEXT_PUBLIC_DRAWIO_BASE_URL`.

### The Next AI Draw.io Application Service

The second service builds from the repository context (`.`) and bundles the Next.js frontend, AI provider backend, and administrative panel. This container exposes port **3000** and declares `depends_on: [drawio]` to ensure the Draw.io service initializes first.

## Step-by-Step Installation

### 1. Clone and Configure Environment Variables

Copy the example environment file and populate it with your AI provider credentials. The `env.example` file in the repository root contains the required variable templates.

```bash

# Clone the repository

git clone https://github.com/DayuanJiang/next-ai-draw-io.git
cd next-ai-draw-io

# Copy environment template

cp env.example .env

# Edit .env to configure AI_PROVIDER, AI_MODEL, and your API keys

```

### 2. Review the Compose Configuration

Examine the [`docker-compose.yml`](https://github.com/DayuanJiang/next-ai-draw-io/blob/main/docker-compose.yml) file to verify the service definitions. The configuration mounts the local `./data` directory to `/app/data` inside the container, ensuring that admin panel settings persist in [`data/settings.json`](https://github.com/DayuanJiang/next-ai-draw-io/blob/main/data/settings.json) across restarts.

```yaml

# docker-compose.yml

services:
  drawio:
    image: jgraph/drawio:latest
    ports:
      - "8080:8080"

  next-ai-draw-io:
    build:
      context: .
      args:
        - NEXT_PUBLIC_DRAWIO_BASE_URL=http://localhost:8080
        # Uncomment for subdirectory deployment:

        # - NEXT_PUBLIC_BASE_PATH=/nextaidrawio

    ports:
      - "3000:3000"
    env_file: .env
    volumes:
      - ./data:/app/data
    depends_on:
      - drawio

```

### 3. Launch the Application Stack

Start both services with Docker Compose. The `depends_on` directive guarantees Docker starts the Draw.io container before the Next.js application attempts to connect.

```bash
docker compose up -d

# Verify services are running

docker compose ps

```

Access the application at `http://localhost:3000`. If you uncommented `NEXT_PUBLIC_BASE_PATH`, use `http://localhost:3000/nextaidrawio` instead.

## Configuration Options

### AI Provider Settings

The Next.js container reads its runtime configuration from the `.env` file specified in the `env_file` directive. Critical variables include:

- **AI_PROVIDER** – Specifies the backend service (e.g., OpenAI, Anthropic)
- **AI_MODEL** – Defines the model identifier for diagram generation
- **API keys** – Provider-specific credentials such as `OPENAI_API_KEY`

### Subdirectory Deployment

For reverse-proxy setups, uncomment the `NEXT_PUBLIC_BASE_PATH` build argument in [`docker-compose.yml`](https://github.com/DayuanJiang/next-ai-draw-io/blob/main/docker-compose.yml). This argument modifies the Next.js build output to serve assets from a subdirectory path rather than the domain root.

### Data Persistence

The volume mapping `./data:/app/data` ensures that administrative configurations survive container recreation. Without this mount, the [`data/settings.json`](https://github.com/DayuanJiang/next-ai-draw-io/blob/main/data/settings.json) file resets to defaults whenever the container restarts.

## Using Pre-Built Images vs. Building Locally

Instead of building from the Dockerfile, reference the GitHub Container Registry image directly:

```yaml
services:
  next-ai-draw-io:
    image: ghcr.io/dayuanjiang/next-ai-draw-io:latest
    ports:
      - "3000:3000"
    env_file: .env
    volumes:
      - ./data:/app/data
    depends_on:
      - drawio

```

This configuration skips the build process while maintaining the same environment variable requirements and volume persistence.

## Summary

- **Two-container architecture**: The stack consists of `jgraph/drawio:latest` (port 8080) and the custom Next.js image (port 3000) defined in [`docker-compose.yml`](https://github.com/DayuanJiang/next-ai-draw-io/blob/main/docker-compose.yml).
- **Dependency management**: The `depends_on` directive ensures the Draw.io service starts before the Next.js application initializes.
- **Configuration persistence**: Mount `./data` to `/app/data` to preserve admin panel settings in [`data/settings.json`](https://github.com/DayuanJiang/next-ai-draw-io/blob/main/data/settings.json).
- **Environment configuration**: Populate `.env` from `env.example` to set `AI_PROVIDER`, `AI_MODEL`, and API credentials.
- **Flexible deployment**: Support for subdirectory hosting via `NEXT_PUBLIC_BASE_PATH` and pre-built images via `ghcr.io/dayuanjiang/next-ai-draw-io:latest`.

## Frequently Asked Questions

### What ports does Next AI Draw.io use when running with Docker Compose?

The Draw.io service exposes port **8080**, while the Next.js application service exposes port **3000**. The application expects the Draw.io instance at `http://localhost:8080` as defined by the `NEXT_PUBLIC_DRAWIO_BASE_URL` environment variable used during the build process.

### How do I persist configuration settings between container restarts?

Mount a local `./data` directory to `/app/data` in the Next.js container. This mapping preserves the [`data/settings.json`](https://github.com/DayuanJiang/next-ai-draw-io/blob/main/data/settings.json) file, which stores admin panel configurations, ensuring settings survive container updates or recreation.

### Can I use a pre-built image instead of building from source?

Yes. Replace the `build` section with `image: ghcr.io/dayuanjiang/next-ai-draw-io:latest` in your [`docker-compose.yml`](https://github.com/DayuanJiang/next-ai-draw-io/blob/main/docker-compose.yml). This approach uses the GitHub Container Registry image and requires the same environment variables and volume mounts as building locally.

### Why does the Next AI Draw.io container depend on the Draw.io service?

The `depends_on: [drawio]` directive ensures Docker starts the Draw.io container before the Next.js application. This startup order guarantees that the `NEXT_PUBLIC_DRAWIO_BASE_URL` endpoint is reachable when the application initializes, preventing connection timeouts on startup.