docs: Add comprehensive deployment and Playwright version management guides, including exact version locking.

Author: purwnt

docs/DEPLOYMENT.md

@@ -309,6 +309,37 @@ nano .env
 docker compose restart
 ```
 
+### Playwright Version Mismatch
+
+**Error**: `Executable doesn't exist at /ms-playwright/...`
+
+**Cause**: Playwright npm version doesn't match Docker image version.
+
+**Solution**:
+```bash
+# Check versions
+cat package.json | grep playwright
+cat Dockerfile | grep playwright
+
+# They should match exactly (e.g., both 1.49.0)
+
+# If not, update package.json to exact version (no ^)
+nano package.json
+# Change "playwright": "^1.49.0" to "playwright": "1.49.0"
+
+# Rebuild with no cache
+docker compose down
+docker compose build --no-cache
+docker compose up -d
+
+# Verify
+docker compose logs -f
+```
+
+**Prevention**: Always use exact Playwright versions in package.json (no `^` or `~`).
+
+See [VERSION_MANAGEMENT.md](VERSION_MANAGEMENT.md) for details.
+
 ## 🔐 Security Best Practices
 
 1. **Use Strong API Key**

docs/VERSION_MANAGEMENT.md

@@ -0,0 +1,119 @@
+# Version Management
+
+## Playwright Version Locking
+
+This project uses **exact version locking** for Playwright to ensure consistency between the Docker image and npm package.
+
+### Current Versions
+
+- **Playwright**: `1.49.0` (exact, no caret)
+- **Docker Image**: `mcr.microsoft.com/playwright:v1.49.0-jammy`
+
+### Why Exact Version?
+
+Playwright requires the browser binaries to match the npm package version exactly. Using `^1.49.0` could install a newer version (e.g., 1.57.0) which won't match the Docker image browsers.
+
+## Updating Playwright
+
+When updating Playwright, you must update **both** files:
+
+### 1. Update package.json
+
+```json
+{
+  "dependencies": {
+    "playwright": "1.XX.0"  // Exact version, no ^
+  }
+}
+```
+
+### 2. Update Dockerfile
+
+```dockerfile
+FROM mcr.microsoft.com/playwright:v1.XX.0-jammy
+```
+
+### 3. Regenerate package-lock.json
+
+```bash
+rm package-lock.json
+npm install
+```
+
+### 4. Test Locally
+
+```bash
+npm start
+# Test endpoints
+```
+
+### 5. Test with Docker
+
+```bash
+docker compose build
+docker compose up
+# Test endpoints
+```
+
+## Version Compatibility Matrix
+
+| Playwright npm | Docker Image | Status |
+|----------------|--------------|--------|
+| 1.49.0 | v1.49.0-jammy | ✅ Current |
+| 1.50.0 | v1.50.0-jammy | ⚠️ Not tested |
+| 1.51.0+ | v1.51.0-jammy+ | ⚠️ Not tested |
+
+## Troubleshooting Version Mismatches
+
+### Error: "Executable doesn't exist"
+
+This means the Playwright npm version doesn't match the Docker image.
+
+**Solution:**
+
+1. Check current versions:
+   ```bash
+   # Check package.json
+   cat package.json | grep playwright
+   
+   # Check Dockerfile
+   cat Dockerfile | grep playwright
+   ```
+
+2. Make sure they match exactly
+
+3. Rebuild:
+   ```bash
+   docker compose down
+   docker compose build --no-cache
+   docker compose up -d
+   ```
+
+### Error: "Please update docker image"
+
+Playwright was updated but Docker image wasn't.
+
+**Solution:**
+
+Update Dockerfile to match the Playwright version in package.json.
+
+## Security Updates
+
+If there's a critical security update for Playwright:
+
+1. Update both package.json and Dockerfile
+2. Test thoroughly
+3. Update this document
+4. Create a new release
+
+## Notes
+
+- Always use exact versions (no `^` or `~`)
+- Keep package.json and Dockerfile in sync
+- Test after every Playwright update
+- Document breaking changes in CHANGELOG.md
+
+---
+
+**Last Updated**: 2025-12-09  
+**Current Playwright Version**: 1.49.0

package-lock.json

@@ -34,7 +34,7 @@
     "dependencies": {
         "@hono/node-server": "^1.13.7",
         "hono": "^4.6.14",
-        "playwright": "^1.49.0"
+        "playwright": "1.49.0"
     },
     "engines": {
         "node": ">=18.0.0"