From f7641a4845b7cb122a5d18e413e0b7b73f1525b6 Mon Sep 17 00:00:00 2001
From: jason <stedwell@gmail.com>
Date: Sun, 8 Mar 2026 15:49:10 -0500
Subject: [PATCH] Add documentation for Docker build fix

---
 DOCKER_BUILD_FIX.md | 94 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 DOCKER_BUILD_FIX.md

diff --git a/DOCKER_BUILD_FIX.md b/DOCKER_BUILD_FIX.md
new file mode 100644
index 0000000..1a58da9
--- /dev/null
+++ b/DOCKER_BUILD_FIX.md
@@ -0,0 +1,94 @@
+# Docker Build Fix - Missing Package Lock Files
+
+## Issue
+Docker build was failing with the following error:
+```
+npm error The `npm ci` command can only install with an existing package-lock.json or
+npm error npm-shrinkwrap.json with lockfileVersion >= 1.
+```
+
+## Root Cause
+The `npm ci` command requires `package-lock.json` files to be present in the repository. These lockfiles were missing from both:
+- `frontend/package-lock.json`
+- `backend/package-lock.json`
+
+## Solution Applied
+
+### Files Added
+1. **frontend/package-lock.json** - Lockfile for frontend dependencies
+2. **backend/package-lock.json** - Lockfile for backend dependencies  
+3. **.dockerignore** - Optimizes Docker build context by excluding unnecessary files
+
+### Why This Matters
+- ✅ **Deterministic builds**: Same dependency versions every time
+- ✅ **Faster CI/CD**: npm ci is faster than npm install
+- ✅ **Better security**: Enables npm audit to detect vulnerabilities
+- ✅ **Production-ready**: Industry best practice for containerized apps
+
+## Next Steps
+
+### Before Merging
+The lockfiles I've created are minimal stubs. You should:
+
+1. **Clone the repository locally**:
+   ```bash
+   git clone https://git.alwisp.com/jason/pnger.git
+   cd pnger
+   git checkout fix/add-package-lockfiles
+   ```
+
+2. **Generate complete lockfiles**:
+   ```bash
+   # Frontend
+   cd frontend
+   rm package-lock.json
+   npm install
+   cd ..
+   
+   # Backend
+   cd backend
+   rm package-lock.json
+   npm install
+   cd ..
+   ```
+
+3. **Commit the complete lockfiles**:
+   ```bash
+   git add frontend/package-lock.json backend/package-lock.json
+   git commit -m "Update with complete dependency lockfiles"
+   git push origin fix/add-package-lockfiles
+   ```
+
+4. **Test Docker build**:
+   ```bash
+   docker build -t pnger:test .
+   ```
+
+### Alternative: Use Current Stub Lockfiles
+If you want to test immediately, the stub lockfiles will allow `npm ci` to run, but npm will still fetch and resolve all dependencies. This works but loses some benefits of lockfiles.
+
+## Build Optimization Added
+
+The `.dockerignore` file now excludes:
+- `node_modules/` (prevents copying local dependencies)
+- Development files (`.env`, `.vscode/`, etc.)
+- Build artifacts (only copied when needed)
+- Documentation and test files
+
+This reduces build context size and speeds up the build process.
+
+## Verification
+
+After merging, verify the fix with:
+```bash
+docker build -t pnger:latest .
+docker run -p 3000:3000 pnger:latest
+```
+
+The build should complete without npm ci errors.
+
+---
+
+**Created**: 2026-03-08  
+**Branch**: `fix/add-package-lockfiles`  
+**Issue**: Docker build failing with missing package-lock.json
\ No newline at end of file