Windsurf
integration
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
Error: Cannot find module 'sharp'
Error: libvips.so.42: cannot open shared object file
Error: Failed to launch the browser process (Puppeteer)
gyp ERR! build error - native module compilation failed
Error: /lib/x86_64-linux-gnu/libm.so.6: version 'GLIBC_2.29' not found
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.
Tejas Chokhawala
Full-stack engineer with 5 years experience building production web apps using React, Next.js and TypeScript.
Focused on performance, clean architecture and shipping fast.
Experienced with Supabase/Postgres backends, Stripe billing, and building AI-assisted developer tools.
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.
Jared Hasson
Full time lead founding dev at a cyber security saas startup, with 10 yoe and a bachelor's in CS. Building & debugging software products is what I've spent my time on for forever
Luca Liberati
I work on monoliths and microservices, backends and frontends, manage K8s clusters and love to design apps architecture
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.
Matt Butler
Software Engineer @ AWS
Nam Tran
10 years as fullstack developer
Basel Issmail
’m a Senior Full-Stack Developer and Tech Lead with experience designing and building scalable web platforms. I work across the full development lifecycle, from translating business requirements into technical architecture to delivering reliable production systems.
My work focuses on modern web technologies, including TypeScript, Angular, Node.js, and cloud-based architectures. I enjoy solving complex technical problems and helping teams turn product ideas and prototypes into working platforms that can grow and scale.
In addition to development, I often collaborate closely with product managers, business analysts, designers, and QA teams to ensure that solutions align with both technical and business goals.
I enjoy working with startups and product teams where I can contribute both as a hands-on engineer and as a technical partner in designing and delivering impactful software.
Antriksh Narang
5 years+ Experienced Dev (Specially in Web Development), can help in python, javascript, react, next.js and full stack web dev technologies.
Matthew Jordan
I've been working at a large software company named Kainos for 2 years, and mainly specialise in Platform Engineering. I regularly enjoy working on software products outside of work, and I'm a huge fan of game development using Unity. I personally enjoy Python & C# in my spare time, but I also specialise in multiple different platform-related technologies from my day job.
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.