Guide: Next.js (Docker Compose)

Use Case

Your Next.js service runs via Compose. You need branch-isolated environments and deterministic port mapping per workspace.

Project Settings Explained

Services

frontend

Spaces assigns each service its own host port per workspace. Compose maps host $SPACES_FRONTEND_PORT to container port 3000.

docker-compose.yml example

services:
  web:
    build: .
    ports:
      - "${SPACES_FRONTEND_PORT}:3000"
    environment:
      - PORT=3000

Setup Script

cp .env.example .env

Copying .env gives each workspace an isolated env file. Symlink can reduce duplication, but one edit impacts all linked workspaces. Point cp at whatever seed file your repo keeps — Spaces does not provide a built-in shared env file.

Processes

SPACES_FRONTEND_PORT=$SPACES_FRONTEND_PORT docker compose up --build

The process keeps Compose attached in one terminal, which is useful for live logs and interactive shutdown.

Browser Sessions

$SPACES_FRONTEND_URL

This targets the workspace-specific service mapping. Without named services, one workspace can accidentally open another workspace's frontend.

Stop Script: stop vs down

docker compose stop
# or
docker compose down

• • docker compose stop: stop containers but keep networks/volumes/containers for faster resume.
• • docker compose down: remove containers and network; cleaner reset, slower next startup.
• • Use stop for day-to-day pause/resume; use down when you need a clean teardown.