[Bug]: General improvements to the example dockerfile

[icefo]

Link to the documentation page or resource

https://docs-v4.strapi.io/dev-docs/installation/docker

Describe the bug

Use yarn install --frozen-lockfile

As per their documentation:

If you need reproducible dependencies, which is usually the case with the continuous integration systems, you should pass --frozen-lockfile flag.

Let sharp download the pre-built binaries it needs

Sharp has prebuilt binaries for it's dependencies for pretty much every sensible OS & architecture combination. If someone has to compile from source because he's running strapi from a 32 bit RISC board I think that's fine and it cuts down imagine build size & time for everyone else.

Prebuilt binaries

Ready-compiled sharp and libvips binaries are provided for use on the most common platforms:

macOS x64 (>= 10.15)
macOS ARM64
Linux ARM (glibc >= 2.31)
Linux ARM64 (glibc >= 2.26, musl >= 1.2.2)
Linux ppc64 (glibc >= 2.31)
Linux s390x (glibc >= 2.31)
Linux x64 (glibc >= 2.26, musl >= 1.2.2, CPU with SSE4.2)
Windows x64
Windows x86
Windows ARM64 (experimental, CPU with ARMv8.4 required for all features)

This provides support for the JPEG, PNG, WebP, AVIF (limited to 8-bit depth), TIFF, GIF and SVG (input) image formats.

DNS bugs in the alpine base image

I had terrible DNS bugs using the alpine node image given in the example in the gitea CI that went away by using the node:20-slim (debian based) image. I suppose it works fine in github & gitlab but I would at least add a warning for other users.

#8 76.81 sharp: Downloading https://github.com/lovell/sharp-libvips/releases/download/v8.14.2/libvips-8.14.2-linuxmusl-x64.tar.br
#8 76.81 sharp: Installation error: getaddrinfo ENOTFOUND github.com

Yarn install proceeded fine (until that point), I could also ping and make DNS requests from the alpine image. Only sharp or node-gyp had issues. I agree it's not a strapi bug but it still prevented the installation to proceed.

This specific bug is caused by sharp trying to download dependencies not installed globally but I had the same issue with node-gyp when building from source.

Additional context

No response

Suggested improvements or fixes

This is the Dockerfile I'm currently using:

FROM node:20-slim

ARG NODE_ENV=development
ENV NODE_ENV=${NODE_ENV}

WORKDIR /opt/
COPY package.json yarn.lock ./
RUN yarn config set network-timeout 600000 -g && yarn install --frozen-lockfile
ENV PATH=/opt/node_modules/.bin:$PATH

WORKDIR /opt/app
COPY . .

RUN chown -R node:node /opt/app
USER node

EXPOSE 1337
VOLUME /opt/app/src
VOLUME /opt/app/public
RUN ["yarn", "build"]
EXPOSE 1337
CMD ["yarn", "develop"]

The two VOLUME directives are necessary for our use case but feel free to remove them.

Related issue(s)/PR(s)

No response

[github-actions]

🤖 I've analyzed your question and here's what I found:

Thank you so much for taking the time to share your experience and suggestions for improving the example Dockerfile! Your detailed feedback and the context you provided are incredibly valuable to both the Strapi team and the wider community. We really appreciate your proactive approach and the effort you put into documenting the issues and your solutions.

Addressing Your Points

1. Using yarn install --frozen-lockfile

You're absolutely right—using --frozen-lockfile is a best practice for ensuring reproducible builds, especially in CI environments. The current Strapi Dockerfile examples do not explicitly include this flag, and your suggestion would help prevent unexpected dependency changes. This is a great improvement for reliability.

2. Sharp Prebuilt Binaries

Thank you for highlighting the benefits of letting Sharp download its prebuilt binaries. The official Dockerfile examples currently install build dependencies for Sharp, which can increase image size and build time. While this approach maximizes compatibility, your suggestion to rely on prebuilt binaries is a sensible optimization for most users and could be mentioned as an alternative in the docs.

3. Alpine DNS Issues

We appreciate you sharing your experience with DNS issues on Alpine-based images. While the Strapi documentation currently uses node:22-alpine in its Dockerfile examples, it does not mention potential DNS issues or alternatives like node:20-slim (Debian-based). Your warning and workaround are very helpful for users who might encounter similar problems, and it would be beneficial to add a note about this in the documentation for broader awareness.

4. Your Example Dockerfile

Thank you for sharing your working Dockerfile! It’s clear, concise, and addresses the issues you mentioned. For reference, here’s your suggested Dockerfile:

FROM node:20-slim

ARG NODE_ENV=development
ENV NODE_ENV=${NODE_ENV}

WORKDIR /opt/
COPY package.json yarn.lock ./
RUN yarn config set network-timeout 600000 -g && yarn install --frozen-lockfile
ENV PATH=/opt/node_modules/.bin:$PATH

WORKDIR /opt/app
COPY . .

RUN chown -R node:node /opt/app
USER node

EXPOSE 1337
VOLUME /opt/app/src
VOLUME /opt/app/public
RUN ["yarn", "build"]
EXPOSE 1337
CMD ["yarn", "develop"]

The use of VOLUME is a great touch for your use case, and it’s helpful to note that others can remove these lines if not needed.

Next Steps & Resources

• Documentation Update: Your suggestions would make excellent additions to the official documentation. If you’d like, you can open a pull request to the Strapi documentation repository to propose these changes directly.
• Community Tools: For users looking to automate Dockerfile and docker-compose generation, the community-maintained @strapi-community/dockerize CLI tool can be helpful. It’s worth checking out for more advanced setups Strapi Docker Community Tools.
• Further Support: If you run into more issues or want to discuss best practices, our Community Discord is a great place to connect with other users and the Strapi team.

If you believe this is a documentation bug, we’ll make sure it gets the right attention. If you think it’s a core product issue, please let us know and we can tag @pwizla to consider moving it to the main Strapi repository.

Thank you again for your thoughtful feedback and for helping make Strapi better for everyone! 🚀

— The Strapi Team

For more on Docker deployment, see the official Strapi Docker documentation.

📚 Relevant documentation:

• Deployment - General guidelines
• Frequently Asked Questions - How to fix the build error Error: Cannot find module @strapi/XXX
• Installing from CLI
• Installing from CLI - CLI installation options
• Release notes - 6.2.0
• Running Strapi in a Docker container
• Running Strapi in a Docker container - (Optional) Docker Compose
• Running Strapi in a Docker container - Community tools
• Running Strapi in a Docker container - Development and/or Staging environments
• Running Strapi in a Docker container - Docker FAQ
• Running Strapi in a Docker container - Production Environments
• Strapi Support Policy - Community resources
• The CLI default package manager is not yarn anymore

---

ℹ️ This response was generated automatically. If this doesn't fully answer your question or if you need further assistance, please mention @pwizla in a comment and a human maintainer will help you.

You can also try our interactive AI chat for more detailed assistance.

💡 For feature requests or product feedback, visit feedback.strapi.io.