Skip to content

Conversation

@kazukinakai
Copy link

@kazukinakai kazukinakai commented Dec 13, 2025

Summary

Adds comprehensive Docker development guidance to the Nx Daemon documentation.

Related to #33263, #30359, #14126

What's included

This PR expands the existing Nx Daemon docs with a new "Running Nx in Docker" section that covers:

  • Why the daemon often fails in Docker - ephemeral filesystems, inode/mtime changes from volume mounts, container restarts, IPC issues
  • Recommended approach - disable daemon with NX_DAEMON=false
  • Example docker-compose setup - minimal reproducible configuration for local development
  • CI/CD best practices - when to prefer stateless builds over daemon caching

Context

Several issues have been opened around daemon behavior in containers, but the existing docs only briefly mention socket location customization. Users are left wondering:

  • Why doesn't the daemon work reliably in Docker?
  • What's the recommended workflow for containerized development?
  • How should CI pipelines handle this?

Issue #33263 specifically describes daemon crashes when running nx between Docker and non-docker environments - this PR documents the recommended workaround (NX_DAEMON=false) and explains why.

Preview

The new section appears under the existing "Customizing the socket location" heading and includes:

  • Explanation of Docker-specific challenges
  • Code examples for Dockerfile, docker-compose, and CLI
  • Rule of thumb callout for quick reference

Open to feedback on structure or placement.

Add comprehensive section explaining:
- Why the daemon often fails in Docker containers
- Recommended approach: disable daemon with NX_DAEMON=false
- Example docker-compose setup for local development
- CI/CD best practices for stateless builds

This addresses common pain points reported in issues nrwl#29384, nrwl#14126, nrwl#30098, and nrwl#8288.
@kazukinakai kazukinakai requested a review from a team as a code owner December 13, 2025 09:04
@kazukinakai kazukinakai requested a review from jaysoo December 13, 2025 09:04
@netlify
Copy link

netlify bot commented Dec 13, 2025

👷 Deploy request for nx-docs pending review.

Visit the deploys page to approve it

Name Link
🔨 Latest commit 1298cc2

@vercel
Copy link

vercel bot commented Dec 13, 2025

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Review Updated (UTC)
nx-dev Ready Ready Preview Dec 13, 2025 9:08am

@distante
Copy link

This isn't a correct workaround. Without the NX daemon, you are stuck with services that doesn't reload after changes. You need to manually stop the container and start it again.

@kazukinakai
Copy link
Author

Good point - you're right that disabling the daemon loses the automatic file watching.

For hot reload without the daemon, the app's bundler (webpack/vite) needs to poll for changes instead:

// webpack.config.js
devServer: {
  watchOptions: {
    poll: 1000,
    ignored: /node_modules/
  }
}

I can add a section covering this trade-off and the polling workaround. Would that address your concern?

@distante
Copy link

I am not on my laptop right now but I think that will not work with projects that runs NestJs applications with the node executor (which is our problem)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants