# MathModelAgent Docker Deployment: Complete Guide to Docker Compose Setup

> Easily deploy MathModelAgent with Docker Compose. Clone the repository and run a single command to launch Redis, FastAPI, and Vue containers for development with hot-reloading.

- Repository: [Sanjin/mathmodelagent](https://github.com/jihe520/mathmodelagent)
- Tags: how-to-guide
- Published: 2026-03-04

---

**To deploy MathModelAgent using Docker Compose, clone the jihe520/mathmodelagent repository and run `docker compose up -d` to launch the Redis broker, FastAPI backend, and Vue frontend containers with hot-reload enabled for development.**

The MathModelAgent system from the `jihe520/mathmodelagent` repository provides a fully containerized development environment. Using the provided [`docker-compose.yml`](https://github.com/jihe520/mathmodelagent/blob/main/docker-compose.yml) configuration, you can orchestrate a three-service stack consisting of a Redis message broker, a Python-based FastAPI backend, and a Vue 3 frontend without installing dependencies manually. This guide explains the complete MathModelAgent Docker deployment process, including architecture details, configuration files, and essential commands for local development.

## Architecture Overview

MathModelAgent runs as a multi-container application with three distinct services defined in [`docker-compose.yml`](https://github.com/jihe520/mathmodelagent/blob/main/docker-compose.yml):

### Redis Service

The **redis** container provides an in-memory broker for task queues and real-time updates. It uses the official `redis:alpine` image, exposes port `6379`, and persists data using the named volume `redis_data`. This service handles message queuing between components without requiring external database configuration.

### Backend Service

The **backend** container runs the FastAPI server that executes the modeling agents. Built from `backend/Dockerfile` using Python 3.12-slim, it installs dependencies via **uv** (a fast Python package manager). The service listens on port `8000`, loads environment variables from `backend/.env.dev` (including `REDIS_URL=redis://redis:6379/0`), and mounts the source code for hot-reload during development. It also uses the `backend_venv` volume to persist the virtual environment across container restarts.

### Frontend Service

The **frontend** container serves the Vue 3 + Vite user interface. Built from `frontend/Dockerfile` using Node 20-alpine and **pnpm** for package management, it runs the development server on port `5173`. The configuration mounts the source code for instant updates and uses an anonymous volume for `node_modules` to prevent cross-platform compatibility issues.

## Prerequisites

Before starting the MathModelAgent Docker deployment, ensure you have:

- Docker Engine 20.10 or newer with Docker Compose v2.0+
- Git installed locally
- Ports `5173`, `8000`, and `6379` available on your machine

## Step-by-Step Deployment Guide

Follow these commands to deploy the complete stack:

1. Clone the repository and navigate to the project directory:

```bash
git clone https://github.com/jihe520/mathmodelagent.git
cd mathmodelagent

```

2. Build and start all services in detached mode:

```bash
docker compose up -d

```

3. Verify that all containers are running:

```bash
docker compose ps

```

You should see output similar to:

```text
NAME                         COMMAND               SERVICE     STATUS
mathmodelagent_backend_1     "uv run uvicorn …"    backend     up
mathmodelagent_frontend_1    "pnpm run dev …"      frontend    up
mathmodelagent_redis_1       "docker-entrypoint.s…" redis       up

```

4. Access the application:
   - Frontend UI: http://localhost:5173
   - API documentation: http://localhost:8000/docs

5. Stop the stack when finished:

```bash
docker compose down          # Stops containers only

docker compose down -v       # Removes containers and named volumes (redis_data, backend_venv)

```

## Key Configuration Files

Understanding these files helps customize your MathModelAgent Docker deployment:

| File | Description |
|------|-------------|
| [`docker-compose.yml`](https://github.com/jihe520/mathmodelagent/blob/main/docker-compose.yml) | Declares the three services, network configuration, and volume mappings. Located at the repository root. |
| `backend/Dockerfile` | Multi-stage build installing Python 3.12, copying [`pyproject.toml`](https://github.com/jihe520/mathmodelagent/blob/main/pyproject.toml) and `uv.lock`, and launching the FastAPI app with uvicorn via `uv`. |
| `frontend/Dockerfile` | Sets up Node 20 Alpine, installs pnpm, copies [`package.json`](https://github.com/jihe520/mathmodelagent/blob/main/package.json) and [`pnpm-lock.yaml`](https://github.com/jihe520/mathmodelagent/blob/main/pnpm-lock.yaml), and starts the Vite dev server. |
| `backend/.env.dev` | Contains environment variables such as `REDIS_URL`. **Note:** This file is referenced by the compose configuration but should not be committed to version control. |
| [`backend/pyproject.toml`](https://github.com/jihe520/mathmodelagent/blob/main/backend/pyproject.toml) | Defines Python dependencies managed by uv. |
| [`frontend/package.json`](https://github.com/jihe520/mathmodelagent/blob/main/frontend/package.json) | Defines Node.js dependencies for the Vue 3 interface. |

## Development Workflow Commands

When actively developing MathModelAgent, use these targeted commands:

**Rebuilding after Dockerfile changes:**

```bash
docker compose up --build -d

```

**Running only the backend (useful for CI pipelines):**

```bash
docker compose up -d backend

```

**Viewing real-time logs:**

```bash
docker compose logs -f backend    # Follow backend logs specifically

docker compose logs -f            # Follow all services

```

Because both the backend and frontend mount source code volumes, changes to your local files are reflected immediately without rebuilding containers.

## Summary

- **MathModelAgent** consists of three containers: Redis (port 6379), FastAPI backend (port 8000), and Vue frontend (port 5173)
- The [`docker-compose.yml`](https://github.com/jihe520/mathmodelagent/blob/main/docker-compose.yml) file orchestrates the stack with persistent volumes for Redis data and the Python virtual environment
- **Hot-reload** is enabled for both backend and frontend through volume mounts, streamlining development
- The backend uses **uv** for fast Python dependency management, while the frontend uses **pnpm** on Node 20 Alpine
- Deployment requires only `docker compose up -d` after cloning the `jihe520/mathmodelagent` repository

## Frequently Asked Questions

### What ports does MathModelAgent expose during Docker deployment?

MathModelAgent exposes three ports: **5173** for the Vue frontend development server, **8000** for the FastAPI backend API, and **6379** for the Redis message broker. These are mapped to your localhost, allowing you to access the UI at `http://localhost:5173` and API documentation at `http://localhost:8000/docs`.

### How do I rebuild containers after modifying a Dockerfile?

Run `docker compose up --build -d` to force a rebuild of the backend and frontend images. This command re-executes the build steps defined in `backend/Dockerfile` and `frontend/Dockerfile` while preserving your named volumes and environment configuration.

### Can I run only the backend service without the frontend?

Yes, you can start individual services using `docker compose up -d backend`. This launches only the FastAPI server and Redis containers, which is useful for API testing or CI/CD pipelines where the user interface is not required.

### Where are environment variables configured in the Docker setup?

Environment variables for the backend are defined in `backend/.env.dev`, which the [`docker-compose.yml`](https://github.com/jihe520/mathmodelagent/blob/main/docker-compose.yml) references via the `env_file` directive. This file typically contains the `REDIS_URL` connection string and other API configuration. The frontend container generally relies on build-time environment variables or Vite's configuration rather than a separate env file in the default setup.