Skip to content

Update Docker documentation with production setup and troubleshooting#3109

Open
pwizla wants to merge 16 commits into
mainfrom
cms/update-docker-documentation
Open

Update Docker documentation with production setup and troubleshooting#3109
pwizla wants to merge 16 commits into
mainfrom
cms/update-docker-documentation

Conversation

@pwizla
Copy link
Copy Markdown
Collaborator

@pwizla pwizla commented Apr 29, 2026 •
edited
Loading

This PR rewrites the Docker documentation page to address user feedback about outdated content.

  • Restructure page into clear sections: development, production, troubleshooting, community tools
  • Add .dockerignore file guidance (prevents architecture mismatches and bloated images)
  • Add .env.example with concrete placeholder values
  • Fix production Dockerfile bug (devDependencies now installed in build stage)
  • Add production docker-compose.prod.yml with PostgreSQL and healthchecks
  • Add HEALTHCHECK directive using Strapi's /_health endpoint
  • Add healthchecks on all database services in docker-compose examples
  • Fix docker-compose: remove deprecated version key, pin mariadb:11.4, use mysql:8.4
  • Add troubleshooting section: Sharp/libvips, Apple Silicon/ARM, database connections
  • Update community tools: add Strapi 5 caution on dockerize, remove abandoned deployify, add naskio/strapi and vshadbolt/strapi community images
  • Add Next steps section
  • Rewrite FAQ in active voice
  • Update Docker card description on installation index page

🤖 Generated with Claude Code

Direct preview link 👉 here

@pwizla @claude
Update Docker documentation with production setup and troubleshooting
eff5255 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@vercel
Copy link
Copy Markdown

vercel Bot commented Apr 29, 2026 •
edited
Loading

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

Project Deployment Actions Updated (UTC)
documentation Ready Ready Preview, Comment May 12, 2026 0:04am

Request Review

@github-actions github-actions Bot added internal PRs created by the Strapi core team pr: updated content PRs updating existing documentation content source: CMS labels Apr 29, 2026
@pwizla pwizla self-assigned this Apr 29, 2026
@pwizla pwizla marked this pull request as draft April 29, 2026 16:13
pwizla and others added 5 commits May 5, 2026 18:13
@pwizla @claude
Apply review feedback and integrity fixes to Docker documentation
bdbb4ba 
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>
@pwizla @claude
Restructure Docker page: reorder sections, move FAQ, format Next steps
ecbcbec 
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>
@pwizla @claude
Remove all Yarn references from Docker documentation
93aa661 
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>
@pwizla @claude
Replace 3 stacked callouts with a production checklist component
3a1dd10 
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>
@pwizla @claude
Replace musl libc jargon with annotation explaining the concept
abda118 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@pwizla pwizla added this to the 6.25.0 milestone May 6, 2026
@pwizla pwizla requested review from derrickmehaffy May 11, 2026 16:10
@pwizla pwizla marked this pull request as ready for review May 11, 2026 16:11
@pwizla pwizla modified the milestones: 6.25.0, 6.26.0 May 11, 2026
@pwizla
Improvements from content review
71ca719 
- 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
@OcneanuVlad
Copy link
Copy Markdown

OcneanuVlad commented May 11, 2026

I see that docusaurus/static/llms-code.txt has some discrepancies like the yarn example for dockerfiles. Do you want to keep that so AI's have a yarn example even though we don't show it in the docs?

@pwizla
Copy link
Copy Markdown
Collaborator Author

pwizla commented May 11, 2026 •
edited
Loading

I see that docusaurus/static/llms-code.txt has some discrepancies like the yarn example for dockerfiles. Do you want to keep that so AI's have a yarn example even though we don't show it in the docs?

Thanks for the comment, @OcneanuVlad!
Please don't worry about LLMs files. No need to review them.
Vercel recreates them as part of the build process, so they're always up-to-date with the latest content.

Actually they shouldn't be included in PRs, I have another open PR that will fix this long-standing issue. It's just that for now, they are also created locally, so you can check them on the local server, but for some reason, if I completely exclude them (.gitignore) the Vercel build breaks 😅 .

derrickmehaffy
derrickmehaffy requested changes May 11, 2026
View reviewed changes
Comment thread docusaurus/docs/cms/installation/docker.md
Comment thread docusaurus/docs/cms/installation/docker.md
Comment thread docusaurus/docs/cms/installation/docker.md Outdated
Comment thread docusaurus/docs/cms/installation/docker.md Outdated
Comment thread docusaurus/docs/cms/installation/docker.md Outdated
pwizla and others added 5 commits May 12, 2026 12:02
@pwizla @claude
Add caution about NODE_ENV ordering in production Dockerfile
20f26df 
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>
@pwizla @claude
Add tip about --virtual cleanup pattern for dev image
ce48334 
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>
@pwizla @claude
Add diagnostic command to Sharp troubleshooting steps
fdf1d14 
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>
@pwizla @claude
Specify dist/build/ as Strapi 5 admin bundle path in COPY tip
5577466 
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>
@pwizla @claude
Note that --omit=dev replaces deprecated --only=production
275e312 
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>
@pwizla
Copy link
Copy Markdown
Collaborator Author

pwizla commented May 12, 2026

Thanks for the review, @derrickmehaffy! Very helpful. Everything should be addressed now.

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

Reviewers

@derrickmehaffy derrickmehaffy Awaiting requested review from derrickmehaffy

Requested changes must be addressed to merge this pull request.

Assignees

@pwizla pwizla

Labels

internal PRs created by the Strapi core team pr: updated content PRs updating existing documentation content source: CMS

Projects

None yet

Milestone

6.26.0

Development

Successfully merging this pull request may close these issues.

3 participants

@pwizla @OcneanuVlad @derrickmehaffy