mozempk/insta-recipe
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(RECIPE-0003): complete iteration 2 - fix Docker deployment

Browse Source 
- Updated Dockerfile base image: node:22-alpine → node:24-alpine
- Regenerated package-lock.json to sync with package.json Tailwind v4
- Docker build now completes successfully (npm ci no longer fails)
- Docker compose with .env.example runs without errors
- Application verified accessible and functional in Docker
- Instagram extraction pipeline tested successfully

Resolves package-lock.json sync issue that blocked iteration 1.
This commit is contained in:
Giancarmine Salucci
2026-02-16 18:26:59 +01:00
parent d55bcf9ae3
commit 8aafbb9d88
5 changed files with 266 additions and 685 deletions
Download Patch File Download Diff File Expand all files Collapse all files

258
docs/FINDINGS.md
View File

@@ -698,6 +698,260 @@ Current Dockerfile is production-ready, only needs VOLUME addition.
---
**Document Version:** 1.2
**Last Updated by:** Planner Agent (RECIPE-0003)
### [Planner] Research Notes - RECIPE-0003 Iteration 1 (2026-02-16)
**Task:** Fix Docker deployment issues (Alpine packages, Playwright installation)
#### Alpine Linux Font Packages
**Research Date:** 2026-02-16
**Source:** https://wiki.alpinelinux.org/wiki/Fonts, Alpine package database
**Incorrect Package Names in Current Dockerfile:**
1. `liberation-fonts` → No such package (ERROR)
2. `noto` → No such package (ERROR)
3. `noto-cjk` → No such package (ERROR)
**Correct Alpine Font Package Names:**
1. `font-liberation` → Correct (already in Dockerfile)
2. `font-noto` → Correct name for Noto fonts
3. `font-noto-cjk` → Correct name for Noto CJK (Chinese, Japanese, Korean) fonts
**Rationale:**
- Alpine Linux uses `font-*` prefix for all font packages
- Common mistake: using Debian/Ubuntu package names which differ from Alpine
- These fonts are essential for rendering text in Instagram content extraction
**Recommended Font Installation:**
```dockerfile
RUN apk add --no-cache \
chromium \
font-liberation \
font-noto \
font-noto-cjk
```
---
#### Playwright on Alpine Linux
**Research Date:** 2026-02-16
**Source:** https://playwright.dev/docs/docker, Playwright GitHub issues
**Official Playwright + Alpine Status:**
- **Not officially supported**: Browser builds require glibc, Alpine uses musl
- **Firefox/WebKit**: Cannot run on Alpine (glibc dependency)
- **Chromium**: Can work using system chromium package
**Problem Analysis:**
- Current Dockerfile installs system chromium via `apk add chromium`
- Playwright's `chromium.launch()` expects Playwright's own Chromium binary
- Playwright's Chromium is built for glibc environments (Ubuntu/Debian)
- `npx playwright install chromium` will download glibc binary that won't run on Alpine
**Solution: Configure Playwright to Use System Chromium**
**Approach A - Use System Chromium (Recommended):**
```typescript
// src/lib/server/browser.ts
browser = await chromium.launch({
executablePath: '/usr/bin/chromium-browser',
headless: true,
args: [...]
});
```
**Environment Variable Approach:**
```dockerfile
ENV PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
ENV PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/usr/bin/chromium-browser
```
**Approach B - Switch to Debian Base:**
```dockerfile
FROM node:22-bookworm
RUN npx -y playwright@1.56.1 install --with-deps chromium
```
**Recommendation:**
- Use Approach A (system chromium with executablePath)
- Minimal changes to existing Alpine setup
- System chromium is already installed and working
- Avoids full base image migration
**Chromium System Dependencies:**
When using system chromium on Alpine, these packages are auto-installed as dependencies:
- ca-certificates, mesa-gbm, wayland-libs-server, libxkbcommon
- ffmpeg-libs, gtk+3.0, libexif, libevent, nss, etc. (64 total dependencies)
---
#### Playwright Version Compatibility
**Research Date:** 2026-02-16
**Source:** package.json analysis
**Current Version:** playwright@1.56.1 (production dependency)
**Chromium Version:** Bundled with Playwright 1.56.1
**System Chromium Compatibility:**
- Alpine edge: chromium 145.0.7632.75 (as of 2026-02-15)
- Playwright 1.56.1 expects: Chromium ~133.x
- **Version mismatch OK**: Playwright API is compatible across minor Chromium versions
- System chromium is newer, should work without issues
**executablePath Configuration:**
- Path on Alpine: `/usr/bin/chromium-browser`
- Must be set in browser.ts or via environment variable
- No additional Playwright installation needed when using system browser
---
#### Docker Compose Configuration for Playwright
**Research Date:** 2026-02-16
**Source:** resolution_context.yaml, docker-compose.yml analysis
**Current Configuration Analysis:**
```yaml
environment:
- DISPLAY=:99 # X11 display (not needed for headless)
security_opt:
- seccomp=unconfined # Required for Chromium sandbox
```
**Issues:**
- `DISPLAY=:99` set but no X11 server (Xvfb) running
- Headless mode doesn't need DISPLAY
- docker-compose.yml has DISPLAY but it's unused
**Recommendation:**
- Keep `DISPLAY=:99` as harmless fallback (no changes needed)
- `seccomp=unconfined` is necessary for Chromium sandbox (keep as-is)
- No additional configuration needed for Playwright
---
---
### [Planner] Node.js Versions and npm Lockfile Compatibility - RECIPE-0003 Iteration 2 (2026-02-16)
**Research Date:** 2026-02-16T17:00:00.000Z
**Source:** Node.js Release Schedule, npm documentation (v10 & v11), Docker Hub
#### Problem Analysis
Docker build fails at `npm ci` with error: "package-lock.json and package.json are out of sync"
- **Root Cause**: package.json updated to Tailwind v4, but package-lock.json still contains Tailwind v3 dependencies (@csstools/*)
- **Secondary Issue**: npm version mismatch - local (npm 11.6.2) vs Docker (npm 10.9.4)
#### Node.js LTS Status Research
**Source:** https://github.com/nodejs/release, https://nodejs.org/en/about/previous-releases
**Currently Supported Versions:**
- **Node.js 20 (Iron)**: Maintenance LTS - EOL 2026-04-30
- **Node.js 22 (Jod)**: Maintenance LTS - EOL 2027-04-30 ← Current Dockerfile
- **Node.js 24 (Krypton)**: Active LTS - EOL 2028-04-30 ← Best choice
- **Node.js 25**: Current (not LTS) - EOL 2026-06-01
**LTS Phase Definitions:**
1. **Current**: Latest features, 6-month cycle for odd versions
2. **Active LTS**: Audited features and updates (18 months for even versions since v12)
3. **Maintenance**: Critical fixes only (12 months)
**Conclusion**: Node.js 24 is Active LTS (until Oct 2026) providing better support than Node.js 22 (already in Maintenance).
#### npm Lockfile Version Compatibility
**Source:** https://docs.npmjs.com/cli/v10/configuring-npm/package-lock-json, https://docs.npmjs.com/cli/v11/configuring-npm/package-lock-json
**Lockfile Version History:**
- `lockfileVersion: 1` - npm v5-v6
- `lockfileVersion: 2` - npm v7-v8 (backwards compatible with v1)
- `lockfileVersion: 3` - npm v9+ (backwards compatible with v7)
**npm Version Bundled with Node.js:**
- node:22-alpine → npm 10.9.4 (uses lockfileVersion: 3)
- node:24-alpine → npm 11.x (uses lockfileVersion: 3)
- Local environment → npm 11.6.2 (uses lockfileVersion: 3)
**Compatibility Analysis:**
- Current package-lock.json has `"lockfileVersion": 3` ✓
- npm 10 and npm 11 both support lockfileVersion: 3 ✓
- The issue is NOT version incompatibility but **stale dependency data**
**npm ci Strict Behavior:**
`npm ci` performs strict validation:
1. Requires exact match between package.json and package-lock.json
2. Does not update lockfile automatically (unlike `npm install`)
3. Fails if dependencies are missing or mismatched
4. This is intentional for reproducible builds in CI/CD
#### Tailwind CSS v3 → v4 Migration Impact
**Source:** package.json analysis, package-lock.json inspection
**Current State:**
```json
// package.json (Tailwind v4)
"@tailwindcss/vite": "^4.1.17",
"tailwindcss": "^4.1.17"
// package-lock.json (still has Tailwind v3 transitive deps)
"@csstools/css-parser-algorithms": "3.0.5",
"@csstools/css-tokenizer": "3.0.4"
```
**Why This Happened:**
- package.json was updated to Tailwind v4
- package-lock.json was NOT regenerated afterward
- Tailwind v4 has different dependency tree than v3 (no @csstools/*)
- `npm ci` detects mismatch and fails
#### Solution Options Analysis
**Option A: Regenerate with Docker node:22-alpine (Review's RECOMMENDED)**
```bash
docker run --rm -v "$PWD":/app -w /app node:22-alpine sh -c "rm package-lock.json && npm install"
```
- ✓ Ensures exact npm version match with deployment
- ✗ Stays on Maintenance LTS (Node 22)
- ✗ Doesn't align with local development (node 24)
**Option B: Update to node:24-alpine**
```dockerfile
FROM node:24-alpine
```
```bash
rm package-lock.json && npm install
```
- ✓ Uses Active LTS (better support)
- ✓ Aligns Docker with local development
- ✗ Changes base image (minimal risk)
**Option C: Hybrid (BEST SOLUTION)**
1. Update Dockerfile to node:24-alpine
2. Regenerate package-lock.json locally (npm 11.x matches node:24)
- ✓ Active LTS with longer support window
- ✓ Perfect alignment between local dev and Docker
- ✓ Single lockfile regeneration
- ✓ Future-proof (Active LTS until Oct 2026)
**Chosen Approach: Option C**
#### Implementation Details
**Files to Modify:**
1. `Dockerfile` - Change FROM node:22-alpine → node:24-alpine
2. `package-lock.json` - Regenerate to sync with package.json
**Verification Steps:**
1. `npm install` - Regenerate lockfile
2. `npm run build` - Verify local build
3. `npm test` - Verify all tests pass
4. `docker build` - Verify Docker build succeeds
5. `docker compose up` - Verify runtime
**No Code Changes Needed:**
- All application code remains unchanged
- .env.example already complete (no new variables)
- docker-compose.yml does not need changes (node version transparent)
---
**Document Version:** 1.4
**Last Updated by:** Planner Agent (RECIPE-0003 Iteration 2)
**Next Update:** Developer Agent