Guide: Next.js + Django Monorepo (Docker)

Use Case

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

Project Settings Explained

Services

frontend
api

Spaces allocates a host port per service per workspace. Compose maps them to container ports.

docker-compose.yml example

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

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

Setup Script

cp .env.example .env

Keeps workspace configuration deterministic. Copy vs symlink tradeoff is the same: isolation vs centralized updates. Point cp at whatever seed file your repo keeps — Spaces does not provide a built-in shared env file.

Process

SPACES_FRONTEND_PORT=$SPACES_FRONTEND_PORT SPACES_API_PORT=$SPACES_API_PORT docker compose up --build

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

Browser Sessions

Add two browser sessions — one URL per entry — so each opens as a Chrome tab when you focus it.

# frontend browser session
$SPACES_FRONTEND_URL

# backend browser session
$SPACES_API_URL/admin

Using named-service 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.