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.
PawelPloszaj
I'm fronted developer with 10+ years of experience with big projects. I have small backend background too
Bastien Labelle
Full stack dev w/ 20+ years of experience
Sage Fulcher
Hey I'm Sage! Im a Boston area software engineer who grew up in South Florida. Ive worked at a ton of cool places like a telehealth kidney care startup that took part in a billion dollar merger (Cricket health/Interwell health), a boutique design agency where I got to work on a ton of exciting startups including a photography education app, a collegiate Esports league and more (Philosophie), a data analytics as a service startup in Cambridge (MA) as well as at Phillips and MIT Lincoln Lab where I designed and developed novel network security visualizations and analytics. I've been writing code and furiously devoted to using computers to make people’s lives easier for about 17 years. My degree is in making computers make pretty lights and sounds. Outside of work I love hip hop, the Celtics, professional wrestling, magic the gathering, photography, drumming, and guitars (both making and playing them)
Antriksh Narang
5 years+ Experienced Dev (Specially in Web Development), can help in python, javascript, react, next.js and full stack web dev technologies.
Victor Denisov
Developer
Omar Faruk
As a Product Engineer at Klasio, I contributed to end-to-end product development, focusing on scalability, performance, and user experience.
My work spanned building and refining core features, developing dynamic website templates, integrating secure and reliable payment gateways, and optimizing the overall system architecture.
I played a key role in creating a scalable and maintainable platform to support educators and learners globally.
I'm enthusiastic about embracing new challenges and making meaningful contributions.
Prakash Prajapati
I’m a Senior Python Developer specializing in building secure, scalable, and highly available systems. I work primarily with Python, Django, FastAPI, Docker, PostgreSQL, and modern AI tooling such as PydanticAI, focusing on clean architecture, strong design principles, and reliable DevOps practices. I enjoy solving complex engineering problems and designing systems that are maintainable, resilient, and built to scale.
Jaime Orts-Caroff
I'm a Senior Android developer, open to work in various fields
MFox
Full-stack professional senior engineer (15+years). Extensive experience in software development, qa, and IP networking.
BurnHavoc
Been around fixing other peoples code for 20 years.
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.