MathModelAgent Docker Deployment: Complete Guide to Docker Compose Setup

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

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:

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

2. Build and start all services in detached mode:

docker compose up -d

3. Verify that all containers are running:

docker compose ps

You should see output similar to:

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:

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	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 and uv.lock, and launching the FastAPI app with uvicorn via uv.
frontend/Dockerfile	Sets up Node 20 Alpine, installs pnpm, copies package.json and 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	Defines Python dependencies managed by uv.
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:

docker compose up --build -d

Running only the backend (useful for CI pipelines):

docker compose up -d backend

Viewing real-time logs:

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

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