Skip to content

Fix Docker quickstart on homepage: missing intl, wrong bin/cake invocation, missing pdo_mysql - #8341

Closed
Nelwhix wants to merge 1 commit into
cakephp:5.xfrom
Nelwhix:fix/docker-quickstart-index
Closed

Nelwhix wants to merge 1 commit into
cakephp:5.xfrom
Nelwhix:fix/docker-quickstart-index

Conversation

@Nelwhix

@Nelwhix Nelwhix commented Sep 24, 2026 •

Copy link
Copy Markdown

Problem

Following the Docker quickstart in docs/en/index.md exactly as written fails
in three separate ways:

  1. docker run -it --rm -v $(pwd):/app composer create-project ... fails
    during dependency resolution:

    cakephp/cakephp requires ext-intl * -> it is missing from your system.

  2. Once a project exists, docker run ... php:8.2-cli php bin/cake server -H 0.0.0.0 doesn't start a server at all. It exits immediately with no
    error, having printed nothing useful.

  3. Even after fixing both of the above, loading the welcome page returns a 500 (Cake\Database\Exception\MissingExtensionException) instead of
    the "green checkmarks" page the docs promise.

Why

  1. The bare composer Docker image doesn't bundle the intl extension,
    which cakephp/cakephp requires. This is the same bug already reported in
    Can't init CakePHP with Docker solution - requires ext-intl * -> it is missing from your system. Install or enable PHP's intl extension. #8319 and fixed in Fix Docker quickstart: install intl before composer create-project #8322 — but that fix only touched
    docs/en/installation.md, not this homepage copy of the same instructions,
    so it was missed here.

  2. bin/cake is a plain POSIX shell script (#!/usr/bin/env sh), not a
    polyglot PHP file. Running php bin/cake ... makes PHP treat the whole
    script as literal HTML output (no <?php tag), print its source, and
    exit 0. It needs to invoke bin/cake.php, the actual PHP entry point.

  3. The scaffolded app's default config/app_local.php points at MySQL, and
    php:8.2-cli has no pdo_mysql. Without it, CakePHP's driver check
    throws before the welcome page can render its normal pass/fail checklist,
    producing a full error page instead of a graceful "problem" row.

Solution

Apply the same install-before-run pattern from #8322 to both Docker commands
on this page: run Composer inside a php:8.2-cli image with intl
installed rather than the bare composer image, install intl and
pdo_mysql before starting the dev server, and call bin/cake.php instead
of bin/cake.

Verified end to end on this patch:

  • create-project scaffolds cakephp/app:~5.4 with no platform requirement
    errors (vendor/, bin/cake.php present)
  • the dev server starts and responds 200 at http://localhost:8765/
  • the welcome page checklist shows PHP version, mbstring, openssl, intl,
    tmp/logs writable, and DebugKit all green; only the (expected, unrelated)
    "no MySQL server running" DB check is red

The homepage Quick Start Docker snippet has the same ext-intl bug already
fixed in installation.md (cakephp#8322), plus two more bugs: `php bin/cake server`
silently no-ops instead of starting a server, and the missing pdo_mysql
extension turns the welcome page's DB check into a hard 500 instead of a
graceful checklist item.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@LordSimal

LordSimal commented Sep 26, 2026 •

Copy link
Copy Markdown
Member

Instead of making our docs way more complicated we are trying to publish our own docker images which already contain the required PHP extensions. See the PR above.

Would that be fine by you as well?

@Nelwhix

Nelwhix commented Sep 26, 2026

Copy link
Copy Markdown
Author

Sure, thank you very much

@Nelwhix Nelwhix closed this Sep 26, 2026
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