From b35eeb3f47c78c3eaa05225f68c6cb9669135755 Mon Sep 17 00:00:00 2001 From: Riddhesh Sanghvi Date: Tue, 17 Nov 2026 18:49:46 +0530 Subject: [PATCH 1/4] fix(site): report failed restarts and reloads, and test the restored php-fpm config run_compose_command() dropped the docker-compose exit code, so `ee site restart` and `ee site reload` exited 0 when a container failed to restart or a reload command failed. It now returns the result: restart and reload finish the remaining containers and then fail, naming the ones that did not restart or reload. `ee site restore` restarted or reloaded the site after its commit and printed "Site restored successfully." whatever happened. The restart now runs with exits captured: on failure the restore says the site was restored but did not start again, and what to run. A failed restart after `update --php` likewise says the PHP version was updated. Before the commit, the restore only tested the nginx config. It now also runs `php-fpm -t` in the site's php container against the restored config, and treats a php.ini syntax error (which `php-fpm -t` accepts) as a failure too, so a pool or php.ini that php-fpm can't load is rolled back instead of committed. --- src/helper/Site_Backup_Restore.php | 35 +++++++++++++++++++++++++-- src/helper/class-ee-site.php | 38 +++++++++++++++++++++++------- src/helper/site-utils.php | 26 +++++++++++++++++++- 3 files changed, 87 insertions(+), 12 deletions(-) diff --git a/src/helper/Site_Backup_Restore.php b/src/helper/Site_Backup_Restore.php index 2845fe78..5096ab55 100644 --- a/src/helper/Site_Backup_Restore.php +++ b/src/helper/Site_Backup_Restore.php @@ -439,18 +439,33 @@ private function run_restore( $backup_dir ) { $this->clear_download_dir(); $this->restore_in_progress = false; + $this->finish_restore(); + } + + /** + * Restart or reload the restored site. The restore is committed, so a failure here must say so rather than exit from inside the restart. + */ + private function finish_restore() { + $action = 'reload'; if ( $this->restore_replaced_app ) { // Mounts inside the containers below /var/www/htdocs (admin-tools' ee-admin, custom compose volumes) stay on the old // directory until the containers start again. EE::log( 'Restarting the site containers.' ); - EE::run_command( [ 'site', 'restart', $this->site_data['site_url'] ], [], [] ); + $action = 'restart'; } else { EE::log( 'Reloading site.' ); - EE::run_command( [ 'site', 'reload', $this->site_data['site_url'] ], [], [] ); } + $started = \EE\Site\Utils\run_without_exit( + function () use ( $action ) { + EE::run_command( [ 'site', $action, $this->site_data['site_url'] ], [], [] ); + } + ); $this->release_site_lock(); + if ( ! $started ) { + EE::error( sprintf( 'The site was restored, but it did not start again. Fix the error above, then run: ee site restart %s', $this->site_data['site_url'] ) ); + } EE::success( 'Site restored successfully.' ); } @@ -1941,6 +1956,7 @@ private function apply_restore_transaction( $backup_dir ) { $this->restore_nginx_conf( $backup_dir ); if ( in_array( $this->site_data['site_type'], [ 'php', 'wp' ], true ) ) { $this->restore_php_conf( $backup_dir ); + $this->check_restored_php_conf(); } $this->check_restored_nginx_conf(); $this->restore_custom_docker_compose( $backup_dir ); @@ -1965,6 +1981,21 @@ private function check_restored_nginx_conf() { } } + /** + * Like the nginx check: php-fpm would not start after the commit. A php.ini syntax error doesn't fail `php-fpm -t`, but + * php then runs without the rest of that file. + */ + private function check_restored_php_conf() { + $test = EE::launch( 'docker-compose -f docker-compose.yml exec -T php php-fpm -t', false, true, [], null, $this->site_data['site_fs_path'] ); + $output = trim( $test->stdout . "\n" . $test->stderr ); + if ( $test->return_code ) { + EE::error( 'The restored php configuration fails `php-fpm -t` in the php container: ' . $output ); + } + if ( preg_match_all( '/^PHP:\s+syntax error.*$/m', $output, $matches ) ) { + EE::error( 'The restored php configuration has a syntax error: ' . implode( ' ', $matches[0] ) ); + } + } + /** * Dump the current DB so a failed restore can put it back. */ diff --git a/src/helper/class-ee-site.php b/src/helper/class-ee-site.php index f34b1546..5ea0ef0f 100644 --- a/src/helper/class-ee-site.php +++ b/src/helper/class-ee-site.php @@ -1020,7 +1020,14 @@ protected function update_php( $args, $assoc_args ) { } EE::error( $e->getMessage() ); } - $this->restart( $args, [ 'php' => true ] ); + $restarted = \EE\Site\Utils\run_without_exit( + function () use ( $args ) { + $this->restart( $args, [ 'php' => true ] ); + } + ); + if ( ! $restarted ) { + EE::error( sprintf( 'Updated site %1$s to PHP version %2$s, but its php container did not restart. Fix the error above, then run: ee site restart %1$s --php', $this->site_data['site_url'], $php_version ) ); + } EE::success( 'Updated site ' . $this->site_data['site_url'] . ' to PHP version: ' . $php_version ); delem_log( 'site php version update end' ); } @@ -1560,19 +1567,22 @@ public function restart( $args, $assoc_args, $whitelisted_containers = [] ) { $containers = array_keys( $assoc_args ); } + $failed = []; foreach ( $containers as $container ) { if ( 'nginx' === $container ) { - if ( EE::exec( \EE_DOCKER::docker_compose_with_custom() . " exec $container nginx -t", true, true ) ) { - \EE\Site\Utils\run_compose_command( 'restart', $container ); - } else { + if ( ! EE::exec( \EE_DOCKER::docker_compose_with_custom() . " exec $container nginx -t", true, true ) ) { \EE\Utils\delem_log( 'site restart stop due to Nginx test failure' ); \EE::error( 'Nginx test failed' ); } - } else { - \EE\Site\Utils\run_compose_command( 'restart', $container ); + } + if ( ! \EE\Site\Utils\run_compose_command( 'restart', $container ) ) { + $failed[] = $container; } } \EE\Utils\delem_log( 'site restart stop' ); + if ( $failed ) { + \EE::error( sprintf( 'Could not restart %s of %s. See the docker-compose output above.', implode( ', ', $failed ), $this->site_data['site_url'] ) ); + } } /** @@ -1717,11 +1727,14 @@ public function reload( $args, $assoc_args, $whitelisted_containers = [], $reloa chdir( $this->site_data['site_fs_path'] ); if ( $all || $no_service_specified ) { - $this->reload_services( $whitelisted_containers, $reload_commands ); + $failed = $this->reload_services( $whitelisted_containers, $reload_commands ); } else { - $this->reload_services( array_keys( $assoc_args ), $reload_commands ); + $failed = $this->reload_services( array_keys( $assoc_args ), $reload_commands ); } \EE\Utils\delem_log( 'site reload stop' ); + if ( $failed ) { + \EE::error( sprintf( 'Could not reload %s of %s. See the docker-compose output above.', implode( ', ', $failed ), $this->site_data['site_url'] ) ); + } } /** @@ -1729,12 +1742,19 @@ public function reload( $args, $assoc_args, $whitelisted_containers = [], $reloa * * @param array $services Services to reload. * @param array $reload_commands Commands to reload the services. + * + * @return string[] The services whose reload command failed. */ private function reload_services( $services, $reload_commands ) { + $failed = []; foreach ( $services as $service ) { - \EE\Site\Utils\run_compose_command( 'exec', $reload_commands[ $service ], 'reload', $service ); + if ( ! \EE\Site\Utils\run_compose_command( 'exec', $reload_commands[ $service ], 'reload', $service ) ) { + $failed[] = $service; + } } + + return $failed; } /** diff --git a/src/helper/site-utils.php b/src/helper/site-utils.php index 2ae2d5c7..b57d92e3 100644 --- a/src/helper/site-utils.php +++ b/src/helper/site-utils.php @@ -848,6 +848,8 @@ function stop_site_containers( $site_fs_path, $containers ) { * @param string $container The container on which action has to be run. * @param string $action_to_display The action message to be displayed. * @param string $service_to_display The service message to be displayed. + * + * @return bool Whether docker-compose exited with 0. */ function run_compose_command( $action, $container, $action_to_display = null, $service_to_display = null ) { @@ -855,7 +857,29 @@ function run_compose_command( $action, $container, $action_to_display = null, $s $display_service = $service_to_display ? $service_to_display : $container; EE::log( ucfirst( $display_action ) . 'ing ' . $display_service ); - EE::exec( \EE_DOCKER::docker_compose_with_custom() . " $action $container", true, true ); + + return EE::exec( \EE_DOCKER::docker_compose_with_custom() . " $action $container", true, true ); +} + +/** + * Call $fn with EE::error() and EE::halt() throwing instead of exiting, for a step after a change that is already done. + * + * @param callable $fn Step to run. + * + * @return bool False when the step exited with a non-zero code. + */ +function run_without_exit( callable $fn ) { + + $previous = EE::set_capture_exit( true ); + try { + $fn(); + } catch ( \EE\ExitException $e ) { + return 0 === $e->getCode(); + } finally { + EE::set_capture_exit( $previous ); + } + + return true; } /** From 425c02d0bcb25b6dc8e07541ed4278eb31771990 Mon Sep 17 00:00:00 2001 From: Riddhesh Sanghvi Date: Tue, 17 Nov 2026 19:06:20 +0530 Subject: [PATCH 2/4] test(behat): run the reload scenario this fixes "Reload fails when the nginx config test fails", left out of the suite as a known bug, comes back as a regular scenario. --- features/restart-reload.feature | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/features/restart-reload.feature b/features/restart-reload.feature index 788b61a7..ec39e7f6 100644 --- a/features/restart-reload.feature +++ b/features/restart-reload.feature @@ -62,3 +62,10 @@ Feature: Restart and reload site services When I write "# Custom Nginx configuration can be put here\n" to the file "{SITES_DIR}/bh-site-command-58.test/config/nginx/custom/user.conf" And I run 'bin/ee site reload bh-site-command-58.test' Then the command should succeed + + Scenario: Reload fails when the nginx config test fails + Given the html site "bh-site-command-57.test" exists + And I write "# Custom Nginx configuration can be put here\nbh_invalid_directive on;\n" to the file "{SITES_DIR}/bh-site-command-57.test/config/nginx/custom/user.conf" + When I run 'bin/ee site reload bh-site-command-57.test' + And I write "# Custom Nginx configuration can be put here\n" to the file "{SITES_DIR}/bh-site-command-57.test/config/nginx/custom/user.conf" + Then the command should fail From 79e3baded03b48a7d23a122e55216334d1bd2cf2 Mon Sep 17 00:00:00 2001 From: Riddhesh Sanghvi Date: Tue, 17 Nov 2026 19:15:40 +0530 Subject: [PATCH 3/4] docs(behat): mark the reload item this fixes as covered --- features/COVERAGE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/features/COVERAGE.md b/features/COVERAGE.md index e00f0f0c..c6da848b 100644 --- a/features/COVERAGE.md +++ b/features/COVERAGE.md @@ -124,7 +124,7 @@ Legend: covered / partial / not covered (reason). Feature files are abbreviated: | restart (no flag, `--nginx`, `--all`), unknown service flag | covered | rr: Restart the site containers (outline); Restart rejects services... | | restart refuses a broken nginx config | covered | rr: Restart refuses a broken nginx config and keeps the site serving | | reload (no flag, `--nginx`, `--all`), custom config applied | covered | rr: Reload nginx... (outline); Custom nginx config is applied on reload | -| reload with a broken config | not covered yet | reload exits 0 when `nginx -t` fails (its scenario comes back with the fix) | +| reload with a broken config | covered | rr: Reload fails when the nginx config test fails | | `custom-compose` config branch of restart/enable | not covered | needs a custom compose setup (config change) | | clean: no flags, `--object`, `--page`, `--proxy` without proxy cache | covered | clean: first four scenarios | | clean `--proxy` with proxy cache | covered (@destructive, regression check for the purge without a terminal) | clean: Cleaning the proxy cache empties it | @@ -224,10 +224,10 @@ DB and container migrations under `migrations/` (core upgrade flow), the AcmePhp ## Coverage estimate -Counting the rows above as items: 124 items, 91 covered, 1 partial, 32 not covered (8 of them, marked "not covered yet", are open bugs whose scenarios come back with their fixes), i.e. about 73% of the inventory. Every user-facing subcommand and option of the html type has at least one scenario except `ssl-renew --force`, `clone --ssl/--wildcard` and a live `share`. +Counting the rows above as items: 124 items, 92 covered, 1 partial, 31 not covered (7 of them, marked "not covered yet", are open bugs whose scenarios come back with their fixes), i.e. about 74% of the inventory. Every user-facing subcommand and option of the html type has at least one scenario except `ssl-renew --force`, `clone --ssl/--wildcard` and a live `share`. ## Known bugs left out -13 scenarios that expose open bugs are not part of this suite; each comes back with the PR that fixes its bug. They cover: the www redirect of a site whose next label starts with `w`, and the redirect after re-enabling a site when the www check fails; the owner lookup of an alias that contains another alias; `update --ssl=inherit` skipping the parent check; the inherit error message dumping the parent site object; the self-signed certificate leaving out alias domains; `ssl-info --get-dns-records` on self-signed sites; `ssl-verify` on a valid Let's Encrypt site; `site reload` exiting 0 when `nginx -t` fails; `site clean` without flags on html sites; invalid `--proxy-cache` values; the removed EE v3 cache flags message; and `update --php` on html sites failing late. +12 scenarios that expose open bugs are not part of this suite; each comes back with the PR that fixes its bug. They cover: the www redirect of a site whose next label starts with `w`, and the redirect after re-enabling a site when the www check fails; the owner lookup of an alias that contains another alias; `update --ssl=inherit` skipping the parent check; the inherit error message dumping the parent site object; the self-signed certificate leaving out alias domains; `ssl-info --get-dns-records` on self-signed sites; `ssl-verify` on a valid Let's Encrypt site; `site clean` without flags on html sites; invalid `--proxy-cache` values; the removed EE v3 cache flags message; and `update --php` on html sites failing late. PRs that change what passing scenarios assert, to revisit when they merge: EasyEngine/site-command#480 keeps `.lock` after a successful backup/restore (drop the two "lock should not exist" lines in backup). From e92c8adcf6ae63e0c5ab50ddeb1d88cc31ea46a4 Mon Sep 17 00:00:00 2001 From: Riddhesh Sanghvi Date: Tue, 17 Nov 2026 20:36:32 +0530 Subject: [PATCH 4/4] fix(restore): report a failed restart of restored custom compose files When a restore brought back custom docker-compose files and the `ee site enable --force` that recreates the containers failed, the restore exited from inside it, after the commit, without saying that the site had been restored. The enable now runs with exits captured. On failure the restore releases the site lock and ends with "The site was restored, but it did not start again. Fix the error above, then run: ee site enable --force". --- src/helper/Site_Backup_Restore.php | 31 ++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/src/helper/Site_Backup_Restore.php b/src/helper/Site_Backup_Restore.php index 5096ab55..8be4eb6f 100644 --- a/src/helper/Site_Backup_Restore.php +++ b/src/helper/Site_Backup_Restore.php @@ -431,21 +431,40 @@ private function run_restore( $backup_dir ) { } // Once per restore (BKP-13), after the commit like the restart below: it recreates the containers. - if ( $this->restore_custom_compose ) { - EE::log( 'Custom docker-compose file(s) updated.' ); - EE::run_command( [ 'site', 'enable', $this->site_data['site_url'] ], [ 'force' => true ] ); - } + $enabled = ! $this->restore_custom_compose || $this->enable_restored_custom_compose(); $this->clear_download_dir(); $this->restore_in_progress = false; - $this->finish_restore(); + $this->finish_restore( $enabled ); + } + + /** + * Recreate the containers for the restored custom compose files, without exiting: the restore is already committed. + * + * @return bool Whether `ee site enable --force` succeeded. + */ + private function enable_restored_custom_compose() { + EE::log( 'Custom docker-compose file(s) updated.' ); + + return \EE\Site\Utils\run_without_exit( + function () { + EE::run_command( [ 'site', 'enable', $this->site_data['site_url'] ], [ 'force' => true ] ); + } + ); } /** * Restart or reload the restored site. The restore is committed, so a failure here must say so rather than exit from inside the restart. + * + * @param bool $enabled False when recreating the containers for restored custom compose files failed: no restart then. */ - private function finish_restore() { + private function finish_restore( $enabled = true ) { + if ( ! $enabled ) { + $this->release_site_lock(); + EE::error( sprintf( 'The site was restored, but it did not start again. Fix the error above, then run: ee site enable %s --force', $this->site_data['site_url'] ) ); + } + $action = 'reload'; if ( $this->restore_replaced_app ) { // Mounts inside the containers below /var/www/htdocs (admin-tools' ee-admin, custom compose volumes) stay on the old