Files
gracesalmoun/docs/production-deployment.md

17 KiB

Production Docker deployment and image-pull diagnosis

Findings and scope

Audit date: 2026-11-11. The reported Kubernetes message means the container image has not been pulled; the application has not started. Its exact cause cannot be identified from that message alone. A Dockerfile change does not repair registry authentication, a missing image/tag, or node networking.

This checkout initially locked Next.js 14.2.30 (React 18.3.1, TypeScript 5.7.2) and declared Node 20.x. Next.js requires Node >=18.17.0. Node 20 is now EOL; the Dockerfile and package engine now use supported Node 24 LTS. A compatible Next.js 14.2.35 patch and non-breaking lockfile security fixes are included. Next.js 14 remains unsupported and still has security advisories. A major framework migration is deliberately outside this Docker-focused change. Do not interpret a successful Docker build as a clean security audit.

The original multi-stage Dockerfile already used npm ci, standalone output, node server.js, port 3000, and host 0.0.0.0. next.config.mjs already enables output: "standalone"; its existing options are preserved. Confirmed gaps:

  • The runtime ran as root and used EOL Node 20.
  • The Docker context allowed environment files, alternate .next* builds, local artifacts, and ZIP source backups. They are now excluded, along with credentials and live CMS state. No actual secret file was found or read.
  • The latest commit added a filesystem CMS, authentication, and uploads. Production reproduction: login 200, upload 200, file exists, immediate image GET 404. Next.js indexes public at startup. A dynamic /uploads/[filename] handler now serves new images without restarting; it accepts only flat image filenames and leaves the existing upload URL/API unchanged.
  • Container testing found /en/resume returning a cached 308 with no HTTP Location header, carrying only a client-side Next.js redirect payload. An explicit Next.js configuration redirect preserves the intended /resume destination for HTTP clients as well as browsers.
  • The runtime creates writable data, public/uploads, and .next/cache directories for UID/GID 1001. Persistent storage remains an operator task.

There is no database client, database connection setting, ORM, migration, Kubernetes manifest, Helm chart, Compose file, or CI workflow in this checkout. The CMS stores data/cms-content.json; initial content is compiled from the TypeScript data modules. All public assets, including the tracked portfolio PDF and existing upload, are copied into the image. No source data directory is needed to read the compiled defaults.

The configured Git remote is https://app.gitpasha.com/boutmoun/gracesalmoun.git, not a GitHub remote. Verify which repository, branch, and commit Ghaymah actually builds. No registry/image name or tag is recorded in this repository.

Build and runtime configuration

Setting Value
Docker build context Repository root (.)
Dockerfile ./Dockerfile
Build npm ci, then npm run build in separate Docker stages
Output .next/standalone, .next/static, public
Container working directory /app
Container start command node server.js (image default)
Runtime user/group nextjs:nodejs, UID/GID 1001:1001
Application address 0.0.0.0:3000
Runtime defaults NODE_ENV=production, PORT=3000, HOSTNAME=0.0.0.0
Health check Unauthenticated HTTP GET / on port 3000; expect 200

Use the image's default command. npm start remains available for a normal local Next.js build, but the standalone container starts node server.js. Do not set NEXT_BUILD_DIR for the image; its build uses .next explicitly. No external API, database, or admin secret is required to build the application.

Environment variable When Requirement
ADMIN_PASSWORD Runtime only Strong private value; missing value disables admin sign-in
ADMIN_COOKIE_SECURE Runtime only true for public HTTPS, including proxy-terminated HTTPS; false for local HTTP testing
NEXT_PUBLIC_SITE_URL Build and runtime Optional public origin; omitted value preserves https://gracesalamoun.com

NEXT_PUBLIC_SITE_URL is compiled into metadata and static robots/sitemap output. A runtime-only override cannot update the already built files. Rebuild when changing it. Existing normalization of known production aliases to https://gracesalamoun.com is retained. Never pass ADMIN_PASSWORD, registry tokens, or private credentials as build arguments or commit them to Git.

Build, test, and prepare an image

Run from the repository root in PowerShell. npm.cmd bypasses this workstation's PowerShell policy restriction on npm.ps1; other shells can use npm.

npm.cmd ci
npm.cmd run build
node node_modules/typescript/bin/tsc --noEmit --incremental false
npm.cmd audit
docker build -t boutmoun:production .

For a different public origin, build with its non-secret value:

docker build --build-arg NEXT_PUBLIC_SITE_URL=https://your-public-domain.example -t boutmoun:production .

Check each exit code before continuing. Lint is currently unconfigured: npm run lint invokes Next.js's interactive ESLint setup; the repository has neither ESLint configuration nor its dependencies. No dependencies were added just to run that setup.

For a local HTTP smoke test, create an untracked .env.docker-smoke containing a temporary ADMIN_PASSWORD and ADMIN_COOKIE_SECURE=false, then run:

docker run --rm --name boutmoun-smoke -p 127.0.0.1:3000:3000 --env-file .env.docker-smoke boutmoun:production

In another terminal, inspect http://localhost:3000/, /ar, /resume, /ar/resume, /admin, /robots.txt, /sitemap.xml, and /documents/grace-salmoun-portfolio.pdf. Check that English redirects still work and unauthenticated /api/admin/content returns 401. Sign in, save a content change, upload an image, and verify the returned image URL immediately. Use disposable volumes when testing save/upload persistence across container recreation. This temporary HTTP test must not use production credentials.

Preserve CMS state before any production replacement

The JSON CMS and image uploads are the application's existing datastore. Back up any deployed data/cms-content.json and the entire public/uploads directory before replacing a running container. Restore them to persistent storage; do not put live data or secrets into a new image.

Attach two persistent volume mounts:

  • /app/data for cms-content.json.
  • /app/public/uploads for uploaded images.

Mount only these directories, not all of /app or /app/public, which would hide bundled application files/assets. New empty volumes can also hide the image's existing upload: seed that directory with the existing bundled uploads as well as any recovered production uploads. Avoid overwriting newer files. Verify that UID/GID 1001 can read/write both mounts. Image ownership does not override volume ownership. With Kubernetes control, fsGroup: 1001 can be used where the storage driver supports it; otherwise provision the mount ownership through the platform's supported storage procedure.

Use one instance with the current JSON-file datastore. It has no concurrent writer coordination; multiple replicas or overlapping rolling replacements can lose updates. Serialize replacement of the writer. Storage architecture changes and a database migration are outside this task.

Ghaymah deployment steps (operator-run; nothing pushed or deployed here)

The documented image-based flow uses an already pushed registry image. No Ghaymah-specific Git build fields or undocumented registry names are assumed.

  1. Verify the connected source repository/branch/commit. If using an existing source-build integration, its Docker context must be the repository root and its Dockerfile Dockerfile. Inspect its build and image-push logs.

  2. Build and test the image above. Choose an actual registry you control and a unique release tag, preferably tied to the final committed Git SHA. Login with a credential manager or interactive prompt; never embed tokens in commands.

  3. When ready to publish, use the same exact full image reference throughout:

    $RegistryServer = Read-Host 'Registry hostname'
    $RegistryImage = Read-Host 'Full registry/repository:unique-tag'
    docker login $RegistryServer
    docker tag boutmoun:production $RegistryImage
    docker push $RegistryImage
    docker buildx imagetools inspect $RegistryImage
    

    Stop on any failed command. Confirm the manifest supports the cluster node architecture. For a multi-platform release, use an initialized Buildx builder and docker buildx build --platform linux/amd64,linux/arm64 -t $RegistryImage --push ., then test the image on each target architecture. That push command is an operator publishing action, not a step executed during this audit.

  4. In Ghaymah, open Apps and edit the existing app, or use Deploy App. Set the image to that exact pushed reference (or digest). Keep the existing app's domains, database connections, and other production settings.

  5. Expose container port 3000, retain the image command, and set the runtime variables described above. For a private image, select/configure the private-registry credential for that registry. A local docker login does not authenticate Ghaymah's Kubernetes nodes.

  6. Attach the backed-up and seeded persistent mounts with correct permissions; use one instance and avoid overlapping writers. Configure the port's HTTP health check to GET / (200), allowing enough startup time. The health check proves HTTP readiness, not CMS write permissions; verify saving separately.

  7. Only after review, update/deploy in the dashboard. Inspect pull/provisioning events first, then runtime logs and health. Repeat the route, login, save, upload, and persistence checks over HTTPS. Retain the previous image digest and data backup for rollback.

Official Ghaymah references: deploying, app fields, registry credentials, ports and health checks, persistent volumes. Dashboard wording may differ; these are documented capabilities, not invented settings for this particular account.

Diagnose the reported Kubernetes image-pull failure

The local kubectl binary has no current context or configured contexts. No cluster requests were made against an assumed cluster. With authorized Ghaymah cluster access, use the actual namespace and current replacement pod if the reported pod has expired:

kubectl config current-context
kubectl get pods -A --field-selector metadata.name=gracesalmounsite-33c5dfa7fb2d-v2-5955767578-ldg5q
$Namespace = Read-Host 'Namespace from the previous output'
$PodName = 'gracesalmounsite-33c5dfa7fb2d-v2-5955767578-ldg5q'
$PodInfo = kubectl get pod $PodName -n $Namespace -o json | ConvertFrom-Json
$PodInfo.spec.containers | Select-Object name,image,imagePullPolicy
$PodInfo.status.containerStatuses | Select-Object name,state
$PodInfo.spec.imagePullSecrets | Select-Object name
$PodInfo.spec | Select-Object serviceAccountName,nodeName
kubectl get events -n $Namespace --field-selector "involvedObject.name=$PodName" --sort-by=.lastTimestamp
kubectl get nodes -L kubernetes.io/arch,kubernetes.io/os
$ServiceAccount = $PodInfo.spec.serviceAccountName
kubectl get serviceaccount $ServiceAccount -n $Namespace -o 'jsonpath={.imagePullSecrets[*].name}'
$PullSecret = Read-Host 'Actual pull-secret name, if used'
kubectl get secret $PullSecret -n $Namespace -o 'jsonpath={.type}'

Do not share raw secret data or unredacted Pod descriptions containing literal environment secrets. Pull-secret metadata should exist in the same namespace and have a valid registry credential type (normally kubernetes.io/dockerconfigjson). Do not print .dockerconfigjson.

After collecting the exact image string from the Pod:

$RegistryImage = Read-Host 'Exact image reference from the Pod'
docker buildx imagetools inspect $RegistryImage
docker pull $RegistryImage

A successful workstation pull proves only workstation access. Nodes may have different credentials, network routes, DNS, CA trust, and CPU architecture.

Event detail Investigation/action
manifest unknown, not found, name unknown Compare full hostname, owner/repository, case, tag/digest with push logs and registry manifest; verify the push actually finished
unauthorized, denied, no basic auth credentials Verify read access, token expiry/scope, correct registry host, Ghaymah credential binding, Pod/service-account pull-secret references, and same-namespace secret existence
FailedToRetrieveImagePullSecret Correct the missing/wrong-namespace secret reference using the platform's credential workflow
no matching manifest Match manifest OS/architecture to the scheduled node; rebuild for that Linux architecture or publish/test a multi-platform manifest
DNS failure, timeout, connection refused Check node-to-registry DNS, routing, firewall/egress and registry availability; local application settings cannot fix this
x509, certificate/TLS error Fix registry certificate chain/hostname or node trust configuration; do not disable TLS verification
429, rate limit Check registry quotas/rate limits and authenticated pull allowance

Without cluster access, collect from Ghaymah: project/app identifier, current revision, complete image reference, selected registry credential name/status (no token), source repository/branch/commit, build and push result/digest, provisioning/Pod event detail, node OS/architecture, and network/TLS errors. The container name in the original error is not the registry image reference. Ask platform support for the Pod Events if only the log error is visible. Do not rotate credentials or retry deployments blindly before reading Events.

References: Kubernetes images and private registries, Next.js standalone output, Node support status, Next.js support policy.

Recorded verification results

Final verification on 2026-11-11:

Check Result
npm.cmd ci after lockfile updates PASS; 108 packages installed reproducibly
npm.cmd run build PASS on Node 24.16.0 / Next.js 14.2.35
TypeScript tsc --noEmit --incremental false PASS
docker build -t boutmoun:production . PASS using Node 24.22.2 Alpine; Linux/amd64
Real container HTTP/admin/storage checks PASS; 58 assertions
npm.cmd run lint with closed stdin UNAVAILABLE / exit 1; interactive setup, ESLint unconfigured
npm.cmd audit FAIL / exit 1; 2 remaining findings: Next.js critical, PostCSS high (including Next.js's bundled PostCSS)
Kubernetes access UNAVAILABLE; no configured contexts/current context, also checked outside sandbox

The Windows build emits a webpack cache-snapshot warning but completes successfully. The Linux Docker build completes without that warning. The security audit is not clean: compatible patches reduced the original seven package findings to two, but Next.js 14 is unsupported. npm proposes a breaking Next.js 16 upgrade for the remaining dependency chain. The user explicitly kept that migration outside scope. Applicability varies by advisory and enabled features; no claim is made that the remaining vulnerabilities are mitigated.

Container tests verified UID 1001, node server.js, 0.0.0.0:3000, English and Arabic home/resume pages, admin page, static CSS/JS, hero image, icon, portfolio PDF, existing upload, both English redirects (308 with correct Location), unauthorized API rejection, invalid password rejection, successful login, HttpOnly/SameSite cookie flags, CMS saves reflected in both languages, immediate upload retrieval with matching bytes/type, missing/invalid image paths, invalid save/upload rejection, absence of secret .env files in the image, logout, and CMS/image persistence across container recreation using two disposable volumes. Test containers and volumes were removed afterward; no production data was modified. This verifies API/HTTP behavior, not a new visual or browser-interaction audit.

The locally retained image is boutmoun:production, image ID sha256:94c3479226d94172f410aa3f80bca98a50145cad357b31fafd3eb2e5e9348afe. It was not pushed to a registry or deployed. Only Linux/amd64 was tested; cluster architecture and registry access remain externally unverified. Ignored local evidence: .artifacts/deployment-smoke-results.json, .artifacts/deployment-audit-before.json, .artifacts/deployment-audit-final.json, and the smoke/reproduction scripts in .artifacts/.

Changed files prepared for review: Dockerfile, .dockerignore, .env.example, .gitignore, package.json, package-lock.json, next.config.mjs, app/uploads/[filename]/route.ts, and this document.