feat: dockerize (multi-stage build, standalone output)

Dockerfile: deps -> builder -> runner. NEXT_PUBLIC_* vars are passed as
build args (inlined into the client bundle at build time, per Next.js);
everything else is read at container runtime instead (docker-compose.yml's
env_file / docker run --env-file) and never baked into an image layer.
Runner stage is non-root, ships only server.js + .next/static + public/
via output: "standalone".

Verified by actually running the build twice locally (Docker itself isn't
available in this environment) -- once with the real .env.local, once with
only placeholder values and no .env.local at all, matching the real Docker
build condition. The second run caught a real, pre-existing bug that had
nothing to do with Docker specifically: /login and three other
client-component trees (location/error, location/permission,
CategoryChips and NeighborhoodSearch nested in Server Component pages) all
call useSearchParams() without a Suspense boundary. next dev tolerates
this; next build hard-fails on it ("missing-suspense-with-csr-bailout").
This would have broken any production build -- Vercel, bare metal,
whatever -- not just Docker; fixed all four by wrapping in <Suspense>.

Also added .env.example (committed, no real values -- .env.local itself
stays gitignored) and a docker-compose.yml, with the --env-file .env.local
requirement called out explicitly in README.md since Compose only
auto-reads a file literally named .env, not .env.local.

.dockerignore

@@ -0,0 +1,11 @@
+node_modules
+.next
+out
+.git
+.env*
+!.env.example
+npm-debug.log*
+*.tsbuildinfo
+next-env.d.ts
+.DS_Store
+README.md

.env.example

@@ -0,0 +1,23 @@
+# Copy to .env.local and fill in real values. See FRONTEND_GUIDE.md for what
+# each of these means; .env.local itself is gitignored, never commit real
+# secrets here.
+
+# Winofy backend (this Django/DRF app)
+WINOFY_API_BASE_URL=https://winofy-staging.winsoo.ir/api
+
+# Gooyal accounts (OAuth2 resource owner password/OTP grant).
+# The browser calls Gooyal directly (its CORS is open), so these are also
+# exposed client-side via the NEXT_PUBLIC_ copies below — the client_secret
+# is intentionally public here, see .env.local's original comment for why.
+GOOYAL_ACCOUNTS_BASE_URL=https://accounts-staging.gooyal.ir
+GOOYAL_CLIENT_ID=
+GOOYAL_CLIENT_SECRET=
+GOOYAL_OAUTH_SCOPE="accounts.account:change_password accounts.account:update accounts.account:retrieve wallet.wallet:get_balance wallet.user:transaction_list data_crud.data:retrieve data_crud.data:update data_crud.data:delete notifications.push:get_client_token accounts.profile:list"
+
+NEXT_PUBLIC_GOOYAL_ACCOUNTS_BASE_URL=https://accounts-staging.gooyal.ir
+NEXT_PUBLIC_GOOYAL_CLIENT_ID=
+NEXT_PUBLIC_GOOYAL_CLIENT_SECRET=
+NEXT_PUBLIC_GOOYAL_OAUTH_SCOPE="accounts.account:change_password accounts.account:update accounts.account:retrieve wallet.wallet:get_balance wallet.user:transaction_list data_crud.data:retrieve data_crud.data:update data_crud.data:delete notifications.push:get_client_token accounts.profile:list"
+
+# Session cookie encryption — generate with: openssl rand -base64 32
+SESSION_SECRET=

.gitignore

@@ -32,6 +32,7 @@ yarn-error.log*
 
 # env files (can opt-in for committing if needed)
 .env*
+!.env.example
 
 # vercel
 .vercel

Dockerfile

@@ -0,0 +1,59 @@
+# syntax=docker/dockerfile:1
+
+# ---- deps: install once, reused by the builder layer -----------------------
+FROM node:24-alpine AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+
+# ---- builder: `next build` with output: "standalone" -----------------------
+FROM node:24-alpine AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# NEXT_PUBLIC_* values are inlined into the client bundle at build time —
+# there is no way to change them later, so they must be passed as build args
+# (see docker-compose.yml, or `docker build --build-arg NEXT_PUBLIC_...=...`).
+ARG NEXT_PUBLIC_GOOYAL_ACCOUNTS_BASE_URL
+ARG NEXT_PUBLIC_GOOYAL_CLIENT_ID
+ARG NEXT_PUBLIC_GOOYAL_CLIENT_SECRET
+ARG NEXT_PUBLIC_GOOYAL_OAUTH_SCOPE
+ENV NEXT_PUBLIC_GOOYAL_ACCOUNTS_BASE_URL=$NEXT_PUBLIC_GOOYAL_ACCOUNTS_BASE_URL \
+    NEXT_PUBLIC_GOOYAL_CLIENT_ID=$NEXT_PUBLIC_GOOYAL_CLIENT_ID \
+    NEXT_PUBLIC_GOOYAL_CLIENT_SECRET=$NEXT_PUBLIC_GOOYAL_CLIENT_SECRET \
+    NEXT_PUBLIC_GOOYAL_OAUTH_SCOPE=$NEXT_PUBLIC_GOOYAL_OAUTH_SCOPE
+
+# Server-only vars are never read at build time (every route that touches them
+# is dynamic — cookies()/no-store fetches — so nothing runs during
+# prerendering), but a couple of modules validate them at import time
+# (e.g. session.ts throws if SESSION_SECRET is missing), so the build still
+# needs *some* value present. Real values are supplied at container runtime
+# instead (see docker-compose.yml / `docker run --env-file`) — never bake a
+# real secret into an image layer.
+ENV WINOFY_API_BASE_URL=https://placeholder.invalid/api \
+    GOOYAL_ACCOUNTS_BASE_URL=https://placeholder.invalid \
+    GOOYAL_CLIENT_ID=placeholder \
+    GOOYAL_CLIENT_SECRET=placeholder \
+    GOOYAL_OAUTH_SCOPE=placeholder \
+    SESSION_SECRET=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
+
+RUN npm run build
+
+# ---- runner: minimal production image ---------------------------------------
+FROM node:24-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production \
+    PORT=3000 \
+    HOSTNAME=0.0.0.0
+
+RUN addgroup -g 1001 -S nodejs && adduser -S nextjs -u 1001
+
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+EXPOSE 3000
+
+CMD ["node", "server.js"]

README.md

@@ -29,6 +29,31 @@ To learn more about Next.js, take a look at the following resources:
 
 You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
 
+## Docker
+
+`NEXT_PUBLIC_*` vars are inlined into the client bundle at *build* time, so they must be passed as build args, not just runtime env — everything else (Gooyal client secret, session secret, API base URL) is read at runtime instead, and should never be baked into an image layer.
+
+**Compose (recommended):**
+```bash
+cp .env.example .env.local   # fill in real values
+docker compose --env-file .env.local up --build
+```
+The `--env-file .env.local` flag matters — without it, Compose falls back to a `.env` file (which this repo doesn't use) for the `NEXT_PUBLIC_*` build-arg substitution in `docker-compose.yml`, and you'll get a client bundle built with empty values.
+
+**Plain `docker build`/`run`:**
+```bash
+docker build \
+  --build-arg NEXT_PUBLIC_GOOYAL_ACCOUNTS_BASE_URL=https://accounts-staging.gooyal.ir \
+  --build-arg NEXT_PUBLIC_GOOYAL_CLIENT_ID=<...> \
+  --build-arg NEXT_PUBLIC_GOOYAL_CLIENT_SECRET=<...> \
+  --build-arg NEXT_PUBLIC_GOOYAL_OAUTH_SCOPE="<...>" \
+  -t winofy .
+
+docker run --env-file .env.local -p 3000:3000 winofy
+```
+
+The image is a multi-stage build using Next's [`output: "standalone"`](https://nextjs.org/docs/app/api-reference/config/next-config-js/output) — the final runtime image ships only `server.js`, `.next/static`, and `public/`, runs as a non-root user, and listens on `$PORT` (default `3000`).
+
 ## Deploy on Vercel
 
 The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.

docker-compose.yml

@@ -0,0 +1,17 @@
+services:
+  web:
+    build:
+      context: .
+      args:
+        # Compose substitutes these from its own env (see the --env-file note
+        # in README.md's Docker section) — NOT from env_file below, which only
+        # affects the running container, not the build.
+        NEXT_PUBLIC_GOOYAL_ACCOUNTS_BASE_URL: ${NEXT_PUBLIC_GOOYAL_ACCOUNTS_BASE_URL}
+        NEXT_PUBLIC_GOOYAL_CLIENT_ID: ${NEXT_PUBLIC_GOOYAL_CLIENT_ID}
+        NEXT_PUBLIC_GOOYAL_CLIENT_SECRET: ${NEXT_PUBLIC_GOOYAL_CLIENT_SECRET}
+        NEXT_PUBLIC_GOOYAL_OAUTH_SCOPE: ${NEXT_PUBLIC_GOOYAL_OAUTH_SCOPE}
+    env_file:
+      - .env.local
+    ports:
+      - "3000:3000"
+    restart: unless-stopped

next.config.ts

@@ -1,6 +1,7 @@
 import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
+  output: "standalone",
   turbopack: {
     root: __dirname,
   },

src/app/(auth)/login/page.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useRef, useState } from "react";
+import { Suspense, useEffect, useRef, useState } from "react";
 import { useRouter, useSearchParams } from "next/navigation";
 import { ArrowRight, ShoppingBag, Store } from "lucide-react";
 import { Button } from "@/components/ui/button";
@@ -20,6 +20,14 @@ type Role = "buyer" | "seller";
 const RESEND_COOLDOWN_SECONDS = 105; // "۱:۴۵" per winofyfrontenddoc.md §2.4 — confirm real value with backend, see doc §2.6.7
 
 export default function LoginPage() {
+  return (
+    <Suspense fallback={null}>
+      <LoginPageInner />
+    </Suspense>
+  );
+}
+
+function LoginPageInner() {
   const router = useRouter();
   const searchParams = useSearchParams();
   const next = searchParams.get("next") ?? "/";

src/app/(customer)/location/error/page.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState } from "react";
+import { Suspense, useState } from "react";
 import { useRouter, useSearchParams } from "next/navigation";
 import { MapPinOff } from "lucide-react";
 import { Button } from "@/components/ui/button";
@@ -9,6 +9,14 @@ import { setLocation } from "@/lib/location/client";
 // L04 — winofyfrontenddoc (1).md §4.2. CTA hierarchy deliberately flips from L01:
 // manual selection is primary here (most likely to succeed), retry is secondary.
 export default function LocationErrorPage() {
+  return (
+    <Suspense fallback={null}>
+      <LocationErrorPageInner />
+    </Suspense>
+  );
+}
+
+function LocationErrorPageInner() {
   const router = useRouter();
   const searchParams = useSearchParams();
   const next = searchParams.get("next") ?? "/";

src/app/(customer)/location/permission/page.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState } from "react";
+import { Suspense, useState } from "react";
 import { useRouter, useSearchParams } from "next/navigation";
 import { MapPin, Zap, Store } from "lucide-react";
 import { Button } from "@/components/ui/button";
@@ -15,6 +15,14 @@ const BENEFITS = [
 // L01 — winofyfrontenddoc (1).md §4.1. No illustration asset was provided;
 // approximated with a simple icon badge rather than the isometric map graphic.
 export default function LocationPermissionPage() {
+  return (
+    <Suspense fallback={null}>
+      <LocationPermissionPageInner />
+    </Suspense>
+  );
+}
+
+function LocationPermissionPageInner() {
   const router = useRouter();
   const searchParams = useSearchParams();
   const next = searchParams.get("next") ?? "/";

src/app/(customer)/location/search/page.tsx

@@ -1,3 +1,4 @@
+import { Suspense } from "react";
 import { winofyFetch, type PaginatedResponse } from "@/lib/api/winofy";
 import { getLocationServer } from "@/lib/location/server";
 import type { Neighborhood } from "@/types/api";
@@ -14,5 +15,9 @@ async function getNeighborhoods() {
 export default async function NeighborhoodSearchPage() {
   const [neighborhoods, location] = await Promise.all([getNeighborhoods(), getLocationServer()]);
   const selectedNeighborhoodUuid = location?.mode === "manual" ? location.neighborhoodUuid : null;
-  return <NeighborhoodSearch neighborhoods={neighborhoods} selectedNeighborhoodUuid={selectedNeighborhoodUuid} />;
+  return (
+    <Suspense fallback={null}>
+      <NeighborhoodSearch neighborhoods={neighborhoods} selectedNeighborhoodUuid={selectedNeighborhoodUuid} />
+    </Suspense>
+  );
 }

src/app/(customer)/page.tsx

@@ -1,3 +1,4 @@
+import { Suspense } from "react";
 import { getValidSession } from "@/lib/auth/session";
 import { getLocationServer } from "@/lib/location/server";
 import { winofyFetch, type PaginatedResponse } from "@/lib/api/winofy";
@@ -63,7 +64,9 @@ export default async function HomePage({ searchParams }: PageProps<"/">) {
 
       <section className="flex flex-col gap-3 pt-4">
         <h2 className="px-4 text-title-large font-bold text-foreground">فروشگاه‌های نزدیک</h2>
-        <CategoryChips categories={categories} />
+        <Suspense fallback={null}>
+          <CategoryChips categories={categories} />
+        </Suspense>
 
         <div className="flex flex-col gap-3 px-4">
           {stores.map((store, index) => (