Guide: Next.js + Django Monorepo (Docker)

Use Case

You need reproducible containerized frontend+backend environments per workspace, with host ports isolated by Muxy.

Project Settings Explained

Port Definitions

FRONTEND_PORT
API_PORT

Muxy allocates host ports per workspace. Compose maps them to container ports.

docker-compose.yml example

services:
  frontend:
    build: ./frontend
    ports:
      - "${FRONTEND_PORT}:3000"
    environment:
      - API_URL=http://backend:8000

  backend:
    build: ./backend
    ports:
      - "${API_PORT}:8000"

Setup Script

cp /shared/.env .env

Keeps workspace configuration deterministic. Copy vs symlink tradeoff is the same: isolation vs centralized updates.

Process

FRONTEND_PORT=$FRONTEND_PORT API_PORT=$API_PORT docker compose up --build

One Compose process starts both services and streams logs in a single terminal.

Browser Sessions

http://localhost:$FRONTEND_PORT
http://localhost:$API_PORT/admin

Using named-port URLs keeps browser targets tied to the correct workspace instance.

Stop Command Strategy

# normal pause
docker compose stop

# full cleanup reset
docker compose down

Prefer stop for faster iteration during normal workflow. Use down when you need to tear down network and container state.

Status Checks

docker ps | grep -q monorepo_frontend
docker ps | grep -q monorepo_backend

Per-service checks reveal partial failure that is otherwise hidden when only the parent Compose process appears alive.