Update Docker documentation with production setup and troubleshooting (#3109)

* Update Docker documentation with production setup and troubleshooting

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Apply review feedback and integrity fixes to Docker documentation

Review changes: remove unverified comments, rewrite ambiguous danger
admonition and move to troubleshooting, reorder DB tabs (PostgreSQL first),
fix contradictory env vars note, document statically compiled admin panel
vars, comment out yarn build in dev Dockerfile, comment out platform
linux/amd64 on DB services, add upload persistence warning, add secrets
management tip, add JS/TS tabs for database config, improve intro with
Docker rationale and community tools pointer, align community H3 headings.

Integrity fixes: add missing ENCRYPTION_KEY to .env and snippet table,
add API_TOKEN_SALT and TRANSFER_TOKEN_SALT to snippet, remove invalid
URL env var from FAQ, fix deprecated npm --only=production flag, update
GCP Container Registry to Artifact Registry, remove unnecessary nasm
package from Alpine dependencies.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Restructure Docker page: reorder sections, move FAQ, format Next steps

Move Community tools before Troubleshooting for better reading flow.
Move Docker FAQ entries to the global /cms/faq page. Replace Next steps
with the Icon-based "What to do next?" format used in the quick start.
Remove nasm from Alpine dependencies (unnecessary for Sharp 0.33.x).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Remove all Yarn references from Docker documentation

Align with PR #3042 (Remove yarn from main pages). Keep npm only
for Dockerfiles, docker-compose volumes, prerequisites, and prose.
Also remove em dash from env vars note.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Replace 3 stacked callouts with a production checklist component

Use the Checklist/ChecklistItem custom component for the production
tips (database ports, upload persistence, secrets management) instead
of 3 consecutive admonitions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Replace musl libc jargon with annotation explaining the concept

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Fix typo and add anchor link in Troubleshooting section

* Fixes following full automated review

* Additional fixes after a second round of self-review

* Improvements from content review

- Add STRAPI_ADMIN_BACKEND_URL ARG to production Dockerfile
- Move commented RUN build to a proper tip callout
- Remove fragile <br/> in tip callout
- Update installation.md intro to match new Docker page scope
- Split dense FAQ paragraph into readable chunks
- Add tip about optimizing production image size with selective COPY
- Clarify npm prerequisite with yarn/pnpm mention
- Improve ENCRYPTION_KEY description in env table
- Add comments on exposed DB ports in dev docker-compose
- Add code example for pool timeout settings in troubleshooting
- Add note about nasm removal from Alpine packages

* Remove highlight markers from HEALTHCHECK and minor callout adjustments

* Add caution about NODE_ENV ordering in production Dockerfile

Warn readers not to set NODE_ENV=production before npm ci,
as npm would skip devDependencies needed for the admin build.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add tip about --virtual cleanup pattern for dev image

Show how to use apk --virtual .build-deps to reduce image size
in the single-stage development Dockerfile.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add diagnostic command to Sharp troubleshooting steps

Add a concrete docker exec test command as the first step,
distinguishing missing library vs. glibc/musl mismatch errors.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Specify dist/build/ as Strapi 5 admin bundle path in COPY tip

Update the selective copy examples to mention the correct path
where the Strapi 5 admin bundle lands.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Note that --omit=dev replaces deprecated --only=production

Add inline comment to help users migrating Dockerfiles from
older Strapi guides that used the now-deprecated npm flag.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: pwizla

docusaurus/docs/cms/faq.md

@@ -18,6 +18,7 @@ tags:
 - typescript
 - database
 - foreign keys
+- docker
 - i18n
 - translations
 
@@ -150,6 +151,23 @@ If you only need wording changes inside **one project** without upstreaming them
 
 You can see the <ExternalLink to="https://feedback.strapi.io/" text="public roadmap"/> to see which feature requests are currently being worked on and which have not been started yet, and to add new feature requests.
 
+## Why doesn't Strapi provide official Docker images?
+
+Strapi is a framework used to build many different types of applications. A single Docker image cannot cover all use cases, so Strapi provides Dockerfile examples instead. See the [Docker installation guide](/cms/installation/docker) for details.
+
+## Why use different Dockerfiles for development and production with Docker?
+
+Strapi builds the admin panel with React and bundles it into the application during the build process. The Strapi backend serves the admin panel as a web server, and the following environment variables are statically compiled into the built admin panel:
+
+- `STRAPI_ADMIN_BACKEND_URL`
+- `ADMIN_PATH` (if using a custom admin path)
+
+Because these values are baked in at build time, you must either pass them as `ARG` in your Dockerfile or rebuild the image when they change. Without this, the admin panel may point to `localhost:1337` instead of your production URL.
+
+Additionally, development images are not optimized for performance and should not be exposed to the public internet. Building separate Docker images for each environment ensures correct configuration and better security.
+
+See the [Docker installation guide](/cms/installation/docker) for full Dockerfile examples.
+
 ## Is there an MCP server for Strapi?
 
 A Strapi MCP (<ExternalLink to="https://www.anthropic.com/news/model-context-protocol" text="Model Context Protocol" />) server is in [development](https://github.com/strapi/strapi/discussions/25398) and will be available soon.

docusaurus/docs/cms/installation.md

@@ -14,6 +14,6 @@ Strapi projects can be installed either locally on a computer or on a remote ser
 
 <CustomDocCard title="CLI" description="Create a project on your local machine using the CLI." link="/cms/installation/cli" />
 
-If you already have an existing Strapi project on your local machine, the following guide provides step-by-step instructions on creating a custom Docker image for your project:
+If you already have an existing Strapi project on your local machine, the following guide covers running it in Docker containers for development and production:
 
-<CustomDocCard title="Docker" description="Create a custom Docker container from a local project." link="/cms/installation/docker" />
+<CustomDocCard title="Docker" description="Build and run a Strapi project in Docker for development and production." link="/cms/installation/docker" />