Guide: Next.js (Docker Compose)

Use Case

Your Next.js service runs via Compose. You need branch-isolated environments, deterministic port mapping, and health checks that detect individual service failure.

Project Settings Explained

Port Definitions

FRONTEND_PORT

Muxy assigns one host port per workspace. Compose maps host $FRONTEND_PORT to container port 3000.

docker-compose.yml example

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

Setup Script

cp /shared/.env .env

Copying .env gives each workspace an isolated env file. Symlink can reduce duplication, but one edit impacts all linked workspaces.

Processes

FRONTEND_PORT=$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

http://localhost:$FRONTEND_PORT

This targets the workspace-specific host mapping. Without named ports, 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.

Status Checks

docker ps | grep -q myapp_web

Status checks make service health explicit in UI and can notify or restart on failure.

Why Status Checks Matter in Compose

• • Key use case: one service in multi-service Compose goes down, but you do not want Compose auto-restart; you still want an immediate notification.
• • Detect partial outage where frontend is up but backend/cache/worker has failed.
• • Alert when a container exists but endpoint is unhealthy (liveness differs from readiness).
• • Trigger controlled restart in Muxy rather than always-on container restart loops.