Dockerfile Missing System Dependencies in Windsurf Project
Your Windsurf-generated Dockerfile builds fail or the container crashes at runtime because system-level dependencies are missing. Node.js native modules like sharp, canvas, bcrypt, or puppeteer require system packages (libvips, libc, chromium) that aren't installed in the Docker image.
Cascade generates a Dockerfile that works for pure JavaScript apps but doesn't account for native dependencies. The build may fail during npm install when compiling native modules, or worse, it may build successfully but crash at runtime when the native module is first loaded.
This is especially common when deploying to production for the first time after developing locally, where system dependencies were already present on the development machine.
Error Messages You Might See
Common Causes
- Sharp requires libvips — The sharp image processing library needs libvips and its dependencies installed at the OS level
- Puppeteer needs Chromium — Puppeteer requires a Chromium installation with many system libraries (libx11, libgbm, libnss3, etc.)
- Canvas requires build tools — The node-canvas package needs build-essential, libcairo2-dev, libpango1.0-dev, and libjpeg-dev
- bcrypt requires compilation tools — Native bcrypt (not bcryptjs) needs python3 and build-essential to compile during npm install
- Alpine image too minimal — Cascade used node:alpine which is missing many libraries. Some packages need the full node:slim or node:bookworm image
- Multi-stage build drops dependencies — A multi-stage Dockerfile installs deps in the build stage but doesn't copy the system libraries to the runtime stage
How to Fix It
- Identify which native modules you use — Check package.json for sharp, canvas, bcrypt, puppeteer, better-sqlite3, or other packages that compile native code
- Add apt-get install for each dependency — Add a RUN apt-get update && apt-get install -y [packages] layer before npm install. Each native module documents its required system packages
- Use node:slim instead of node:alpine — Alpine uses musl libc which causes issues with many native modules. node:slim (Debian-based) has better compatibility
- Copy system libraries in multi-stage builds — If using multi-stage, COPY --from=builder /usr/lib/ and other library paths needed by native modules
- Use pre-built binaries where possible — Sharp and bcrypt offer pre-built binaries for common platforms. Ensure your Dockerfile platform matches and npm can download them
- Test the Docker build locally — Run docker build and docker run locally before deploying. Test the specific features that use native modules
Real developers can help you.
BurnHavoc
Been around fixing other peoples code for 20 years.
Yovel Cohen
I got a lot of experience in building Long-horizon AI Agents in production, Backend apps that scale to millions of users and frontend knowledge as well.
Vlad Temian
15+ years shipping production infrastructure for startups. Former CTO at qed.builders (acquired by The Sandbox).
Cursor ambassador and agentic tooling builder.
I've scaled systems, automated deployments, and built observability tools for AI coding workflows. I specialize in taking vibe-coded apps from broken prototype to production-ready: fixing Supabase auth/RLS, Stripe integrations, deployment pipelines, and cleaning up AI-generated spaghetti.
I build tools in this space (agentprobe, claudebin, micode) and understand both sides: how AI generates code and why it breaks.
https://blog.vtemian.com/
Franck Plazanet
I am a Strategic Engineering Leader with over 8 years of experience building high-availability enterprise systems and scaling high-performing technical teams. My focus is on bridging the gap between complex technology and business growth.
Core Expertise:
🚀 Leadership: Managing and coaching teams of 15+ engineers, fostering a culture of accountability and continuous improvement.
🏗️ Architecture: Enterprise Core Systems, Multi-system Integration (ERP/API/ETL), and Core Database Structure.
☁️ Cloud & Scale: AWS Expert; architected systems handling 10B+ monthly requests and managing 100k+ SKUs.
📈 Business Impact: Aligning tech strategy with P&L goals to drive $70k+ in monthly recurring revenue.
I thrive on "out-of-the-box" thinking to solve complex technical bottlenecks and am always looking for ways to use automation to improve business productivity.
Krishna Sai Kuncha
Experienced Professional Full stack Developer with 8+ years of experience across react, python, js, ts, golang and react-native. Developed inhouse websearch tooling for AI before websearch was solved : )
Richard McSorley
Full-Stack Software Engineer with 8+ years building high-performance applications for enterprise clients. Shipped production systems at Walmart (4,000+ stores), Cigna (20M+ users), and Arkansas Blue Cross. 5 patents in retail/supply chain tech. Currently focused on AI integrations, automation tools, and TypeScript-first architectures.
MFox
Full-stack professional senior engineer (15+years). Extensive experience in software development, qa, and IP networking.
Anthony Akpan
Developer with 8 years of experience building softwares fro startups
Antriksh Narang
5 years+ Experienced Dev (Specially in Web Development), can help in python, javascript, react, next.js and full stack web dev technologies.
Nam Tran
10 years as fullstack developer
You don't need to be technical. Just describe what's wrong and a verified developer will handle the rest.
Get HelpFrequently Asked Questions
Should I use node:alpine or node:slim for my Dockerfile?
Use node:slim (Debian-based) unless you specifically need Alpine's small size and have verified all your dependencies work on Alpine. Alpine uses musl libc instead of glibc, which breaks many native Node.js modules like sharp, canvas, and bcrypt.
Why does my app work locally but crash in Docker?
Your local machine has system libraries pre-installed (from Homebrew, apt, etc.) that your Docker image doesn't have. Docker starts with a minimal OS, so every system dependency must be explicitly installed in the Dockerfile.