Refine Docker config and env sample

app/frontend/Dockerfile

@@ -1,108 +1,71 @@
 #
 # FRONTEND DOCKERFILE
 #
-# This Dockerfile builds the container for the Next.js frontend application.
-# It uses a multi-stage build process to create lean, optimized images for
-# production while providing a flexible environment for development.
+# Multi-stage image for the Next.js SPA/SSR frontend.
+# - runner: production server with minimal footprint
+# - builder: compiles the Next.js app
+# - dev: hot-reload friendly image
 #
-# Stages:
-# - `base`:    Installs Node.js and sets up a non-root user.
-# - `deps`:    Installs npm dependencies.
-# - `builder`: Builds the Next.js application for production.
-# - `runner`:  A minimal production-ready image that serves the built app.
-# - `dev`:     A development-ready image with hot-reloading enabled.
-#
-# For more details, see: ./docs/architecture.md
+# COMPOSE_PROFILES decides which stage is used by docker-compose.yml.
 #
 
-# ------------------------------------------------------------------------------
-#   1. Base Stage
-#      - Installs Node.js and sets up a non-root user for security.
-# ------------------------------------------------------------------------------
-FROM node:20-slim AS base
-
-# Set environment variables for non-interactive installation.
-ENV NPM_CONFIG_LOGLEVEL=warn
-
-# Create a non-root user and group for running the application.
-# This is a critical security measure to avoid running as root.
-RUN addgroup --system --gid 1001 nextjs
-RUN adduser --system --uid 1001 nextjs
-
-# ------------------------------------------------------------------------------
-#   2. Dependencies Stage
-#      - Installs npm dependencies. This layer is cached to speed up builds
-#        when only source code changes.
-# ------------------------------------------------------------------------------
-FROM base AS deps
-
+FROM node:22-slim AS base
 WORKDIR /app
 
-# Copy the package manager files.
-COPY package.json package-lock.json* ./
+ENV NPM_CONFIG_LOGLEVEL=warn \
+    NODE_OPTIONS="--enable-source-maps"
 
-# Install dependencies.
+# ------------------------------------------------------------------------------
+# Dependencies cache
+# ------------------------------------------------------------------------------
+FROM base AS deps
+COPY package.json package-lock.json* ./
 RUN npm ci
 
 # ------------------------------------------------------------------------------
-#   3. Builder Stage
-#      - Builds the Next.js application for production.
+# Production dependencies only (pruned to omit dev tooling)
+# ------------------------------------------------------------------------------
+FROM base AS prod-deps
+COPY package.json package-lock.json* ./
+RUN npm ci --omit=dev
+
+# ------------------------------------------------------------------------------
+# Builder: compile the application for production
 # ------------------------------------------------------------------------------
 FROM base AS builder
 
-WORKDIR /app
-
-# Copy dependencies from the `deps` stage.
 COPY --from=deps /app/node_modules ./node_modules
-# Copy the application source code.
 COPY . .
-
-# Build the Next.js application. This creates an optimized production build
-# in the .next/ directory.
+ENV NODE_ENV=production
 RUN npm run build
 
 # ------------------------------------------------------------------------------
-#   4. Runner Stage (Production)
-#      - Creates a minimal, secure image for serving the production application.
+# Production runner: serve the built Next.js app
 # ------------------------------------------------------------------------------
-FROM base AS runner
-
+FROM node:22-slim AS runner
 WORKDIR /app
 
-# Set the environment to "production". This tells Next.js to use the
-# optimized build and enables other production-specific behaviors.
-ENV NODE_ENV=production
+ENV NODE_ENV=production \
+    NEXT_TELEMETRY_DISABLED=1
 
-# Switch to the non-root user.
-USER nextjs
+USER node
+COPY --from=prod-deps --chown=node:node /app/node_modules ./node_modules
+COPY --from=builder --chown=node:node /app/.next ./.next
+COPY --from=builder --chown=node:node /app/public ./public
+COPY --from=builder --chown=node:node /app/package.json ./package.json
 
-# Copy the built application from the `builder` stage.
-# We copy only the necessary files to keep the image small.
-COPY --from=builder --chown=nextjs:nextjs /app/public ./public
-COPY --from=builder --chown=nextjs:nextjs /app/.next ./.next
-COPY --from=builder --chown=nextjs:nextjs /app/node_modules ./node_modules
-COPY --from=builder --chown=nextjs:nextjs /app/package.json ./package.json
-
-# Expose the port the Next.js server will run on.
 EXPOSE 3000
-
-# The command to start the Next.js server in production mode.
-CMD ["npm", "start"]
+CMD ["npm", "run", "start"]
 
 # ------------------------------------------------------------------------------
-#   5. Dev Stage (Development)
-#      - Creates an image for local development with hot-reloading.
+# Development: keeps node_modules and sources mounted for hot reload
 # ------------------------------------------------------------------------------
-FROM base AS dev
-
+FROM deps AS dev
 WORKDIR /app
 
-# Copy dependencies from the `deps` stage.
-COPY --from=deps /app/node_modules ./node_modules
+ENV NODE_ENV=development \
+    NEXT_TELEMETRY_DISABLED=1
 
-# Expose the development port.
+USER node
 EXPOSE 3000
-
-# The command to start the Next.js development server.
-# This will be overridden by the docker-compose file for bind mounting.
-CMD ["npm", "run", "dev"]
+CMD ["npm", "run", "dev", "--", "--hostname", "0.0.0.0", "--port", "3000"]