feat: site atomic deployments by loadinglucian · Pull Request #98 · loadinglucian/deployer-php

loadinglucian · 2025-11-20T15:58:24Z

Summary by CodeRabbit

New Features
- Interactive site deployment command with PHP-version choice, release retention, hooks handling, replay snippet and post-deploy summary.
- Log viewer now shows PHP‑FPM and per‑site file logs with error‑line highlighting.
Improvements
- Automatic linking of shared resources during deployments.
- Ensure Composer is present before PHP package installation.
- Adopt atomic release layout and add full atomic site‑deploy and site‑linking playbooks/scripts.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

…releases - Add site:deploy command for orchestrating deployments - Implement site-deploy.sh playbook with git-based releases - Create timestamped releases with shared resources - Add deployment hooks support (1-building, 2-releasing, 3-finishing) - Register command in SymfonyApp - Include PHP version selection and release cleanup

- Add site-link-shared.sh playbook for linking shared files - Enhance site:shared:push to automatically link uploaded files - Add link_shared_resources() helper function in helpers.sh - Support symlinking shared resources to current release

- Add PHP-FPM log viewing for all detected PHP versions - Add site access log viewing for Caddy sites - Enhance service detection to include PHP and sites - Add error highlighting in log output - Update command description to reflect expanded capabilities

…te support - Use DEPLOYER_PHP environment variable in 1-building.sh hook - Add SQLite database setup example in 2-releasing.sh hook - Ensure hooks use correct PHP binary for composer/artisan commands

- Install Composer automatically in install-php.sh playbook - Improve directory permissions in site-add.sh (755 for proper execution) - Ensure deployment infrastructure supports PHP tooling

coderabbitai · 2025-11-20T15:58:35Z

Walkthrough

Adds a SiteDeployCommand and atomic site deployment playbooks/scripts; enhances ServerLogsCommand to detect PHP‑FPM and per‑site file logs with error highlighting; updates SiteSharedPushCommand to link shared files after upload; adds playbook helpers and tweaks install/site scaffolds and hook scripts.

Changes

Cohort / File(s)	Summary
Server logs & helpers `app/Console/Server/ServerLogsCommand.php`	Reworked processed result shape to include `options`, `services`, `phpVersions`, `sites`, `hasDocker`; added `retrieveFileLogs()` and `highlightErrors()`; lowercased/typed detected services; display flow now includes system, service journal logs, PHP‑FPM file logs, site file logs and Docker; file paths escaped when tailing.
Site deploy command `app/Console/Site/SiteDeployCommand.php`	New `site:deploy` Symfony command: selects site, validates hooks, resolves branch/php/keep‑releases, prompts, runs `site-deploy.sh` via playbooks with DEPLOYER_* env vars, prints deployment summary and replay snippet; new helpers for resolving PHP and keep‑releases and checking hooks.
Command registration `app/SymfonyApp.php`	Registers `SiteDeployCommand` in application command list and adds import.
Site shared push `app/Console/Site/SiteSharedPushCommand.php`	After upload, runs `site-link-shared.sh` with `DEPLOYER_DISTRO`/`DEPLOYER_PERMS`/`DEPLOYER_SITE_DOMAIN`; returns early on playbook error; updates success message to indicate upload + link.
Deployment playbooks `playbooks/site-deploy.sh`, `playbooks/site-link-shared.sh`	`site-deploy.sh`: atomic release workflow (prepare dirs, detect PHP, clone/update bare repo, build release, link shared, run hooks 1/2/3, activate release, reload PHP‑FPM, cleanup, write YAML output). `site-link-shared.sh`: validates env, resolves release, calls `link_shared_resources`, writes YAML output.
Playbook helpers & PHP install `playbooks/helpers.sh`, `playbooks/install-php.sh`, `playbooks/site-add.sh`	`helpers.sh`: adds `run_as_deployer()`, `fail()`, `link_shared_resources()`. `install-php.sh`: preflight installs Composer if missing. `site-add.sh`: switch to atomic dirs (releases/shared/repo/current) and set directory perms to 755.
Hook scaffolds `scaffolds/hooks/1-building.sh`, `scaffolds/hooks/2-releasing.sh`	`1-building.sh`: run Composer via discovered composer binary invoked through `DEPLOYER_PHP`. `2-releasing.sh`: adds commented SQLite shared-db scaffold (no active behavior).

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant SiteDeployCmd as SiteDeployCommand
    participant PlaybooksTrait
    participant SiteScript as site-deploy.sh
    participant Hooks as Hook Scripts
    participant PHP as PHP-FPM

    User->>SiteDeployCmd: run site:deploy
    SiteDeployCmd->>SiteDeployCmd: select site, validate hooks, resolve branch/php/keep
    SiteDeployCmd->>User: request confirmation
    User-->>SiteDeployCmd: approve
    SiteDeployCmd->>PlaybooksTrait: executePlaybook(site-deploy) with DEPLOYER_*
    PlaybooksTrait->>SiteScript: start deployment
    SiteScript->>SiteScript: prepare_directories(), detect PHP, clone_or_update_repo(), build_release()
    SiteScript->>SiteScript: link_shared_resources(), run_hook(1-building.sh), run_hook(2-releasing.sh)
    SiteScript->>SiteScript: activate_release(), run_hook(3-finishing.sh)
    SiteScript->>PHP: reload_php_fpm()
    SiteScript->>SiteScript: cleanup_releases(), write_output(YAML)
    SiteScript-->>PlaybooksTrait: success
    PlaybooksTrait-->>SiteDeployCmd: result
    SiteDeployCmd->>User: display summary & next steps

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Files warranting extra attention:
- playbooks/site-deploy.sh (git/bare-repo flow, release activation, cleanup, YAML output)
- playbooks/helpers.sh / playbooks/site-link-shared.sh (permission-aware linking, run_as_deployer and fail semantics)
- app/Console/Server/ServerLogsCommand.php (path escaping, retrieveFileLogs integration, highlightErrors regex/output)

Possibly related PRs

bigpixelrocket/deployer-php#92 — touches SiteSharedPushCommand; related because both PRs modify shared-file upload/link flow.
bigpixelrocket/deployer-php#68 — earlier changes to ServerLogsCommand; directly related to the server log handling refactor here.
bigpixelrocket/deployer-php#64 — changes to PlaybooksTrait / executePlaybook signatures; relevant to new SiteDeployCommand playbook execution.

Poem

🐰
I hop between releases, tidy and spry,
Symlinks click, hooks hum — watch code sail by,
PHP wakes, logs shimmer where bugs once lay,
Atomic hops keep messy deploys at bay,
A carrot for each clean, successful try.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: site atomic deployments' directly and clearly summarizes the main change: introducing atomic deployment functionality for sites throughout the codebase.
Docstring Coverage	✅ Passed	Docstring coverage is 97.30% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch feat/site-atomic-deployments

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 4

🧹 Nitpick comments (9)

app/Console/Server/ServerLogsCommand.php (2)
123-214: Processed services/php versions/sites wiring looks solid; consider deduping versions

The extended getProcessedServices() correctly:

Filters and normalizes detected services.

Tracks Docker separately.

Extracts PHP versions from both scalar and array-shaped entries.

Derives site names from sites_config.

Exposes a single options map plus structured services/phpVersions/sites/hasDocker for downstream use.

One minor improvement: if info['php']['versions'] can contain duplicates, you may end up with duplicate "phpX.Y-fpm" entries in $options. A simple array_unique() on $phpVersions before building options would keep the select list clean and deterministic.

For example:
-        $phpVersions = [];
+        $phpVersions = [];
         if (isset($info['php']) && is_array($info['php']) && isset($info['php']['versions']) && is_array($info['php']['versions'])) {
             foreach ($info['php']['versions'] as $versionData) {
                 // ...
             }
         }
+
+        $phpVersions = array_values(array_unique($phpVersions));
321-337: File-based log retrieval and error highlighting are well factored; minor perf nit only

The new pieces work together nicely:

retrieveServiceLogs() and tryTraditionalLogs() now consistently route output through highlightErrors(), giving a unified view for both journalctl and file logs.

retrieveFileLogs() provides a clear, reusable abstraction for PHP-FPM and site logs, including a helpful “File:” line and graceful “No logs found” messaging.

highlightErrors() is simple and effective at flagging likely-problematic lines.

One tiny micro-optimisation (non-blocking): in highlightErrors(), you recompute strtolower($keyword) on every iteration. Pre-lowering the keywords once would avoid that inner-loop work:
-        $keywords = [
+        $keywords = [
             'error',
             'exception',
             'fail',
             'failed',
             'fatal',
             'panic',
             ' 500 ',
             ' 502 ',
             ' 503 ',
             ' 504 ',
         ];
-
-        $lines = explode("\n", $content);
+        $keywords = array_map('strtolower', $keywords);
+        $lines = explode("\n", $content);
@@
-            foreach ($keywords as $keyword) {
-                if (str_contains($lowerLine, strtolower($keyword))) {
+            foreach ($keywords as $keyword) {
+                if (str_contains($lowerLine, $keyword)) {
                     $hasError = true;
                     break;
                 }
             }
Not required, just a small efficiency tweak if logs get large.

Also applies to: 344-365, 392-392, 422-463
playbooks/helpers.sh (2)
33-39: run_as_deployer helper is fine; relies on callers to set PRESERVE_ENV_VARS

The run_as_deployer wrapper correctly routes through sudo -n -u deployer when DEPLOYER_PERMS is root|sudo, and falls back to direct execution otherwise. It assumes PRESERVE_ENV_VARS is set by the calling playbook, which site-deploy.sh and site-link-shared.sh now do, so the preserved env set is under the caller’s control.

Nothing to fix here; just keep the contract (“caller must define PRESERVE_ENV_VARS”) in mind for future playbooks.

182-207: link_shared_resources is robust; consider minimal guard on RELEASE_PATH/SHARED_PATH

The shared-resource linker is careful about:

No-op when $SHARED_PATH is missing or empty

Per-item rm-then-symlink with run_cmd/run_as_deployer

Hard-failing via fail() if removal or linking fails

Given the use of rm -rf "$release_item", it’s important that all call sites guarantee sane SHARED_PATH/RELEASE_PATH values (which site-deploy.sh and site-link-shared.sh do). As a belt-and-suspenders safety net, you could add a quick sanity check at the start:
[[ -z $SHARED_PATH || -z $RELEASE_PATH ]] && fail "SHARED_PATH and RELEASE_PATH must be set"
Not strictly required with the current callers, but reduces risk if this helper gets reused elsewhere.
playbooks/site-link-shared.sh (1)
42-46: PRESERVE_ENV_VARS ShellCheck warning is a false positive in this context

PRESERVE_ENV_VARS is set here and then consumed indirectly by run_as_deployer from the inlined helpers.sh (via --preserve-env="$PRESERVE_ENV_VARS"). ShellCheck doesn’t see that use when analyzing this file in isolation, hence SC2034.

You don’t need to change behavior, but adding a brief comment can make the intent clearer and quiet future confusion, e.g.:
# Used by run_as_deployer in helpers.sh to preserve these vars under sudo
PRESERVE_ENV_VARS="DEPLOYER_SHARED_PATH,DEPLOYER_RELEASE_PATH,DEPLOYER_DISTRO,DEPLOYER_PERMS"
playbooks/site-deploy.sh (2)
49-61: Env validation and preserved-variable setup look consistent with helpers

The required DEPLOYER_* variables are validated early and DEPLOYER_KEEP_RELEASES is sanitized to a positive integer, which matches the PHP-side validation in SiteDeployCommand. Exporting DEPLOYER_RELEASE_PATH, DEPLOYER_SHARED_PATH, DEPLOYER_CURRENT_PATH, DEPLOYER_REPO_PATH, etc. plus the PRESERVE_ENV_VARS list aligns with run_as_deployer’s --preserve-env usage.

ShellCheck’s SC2034 about PRESERVE_ENV_VARS being unused is again a per-file false positive; it is consumed by the helper function. No behavioral change needed.

Also applies to: 73-81

181-237: End-to-end deployment flow is coherent; watch for assumptions about PHP-FPM service presence

The overall sequence:

clone_or_update_repo with host key management

build_release via git archive into a timestamped directory

link_shared_resources (from helpers)

Hook chain (1-building.sh, 2-releasing.sh, 3-finishing.sh)

activate_release + reload_php_fpm + cleanup_releases

is well-structured and matches the atomic layout created by site-add.sh. The use of fail() keeps failures clear and early.

One assumption to keep in mind is reload_php_fpm() unconditionally doing:
run_cmd systemctl reload "php${DEPLOYER_PHP_VERSION}-fpm" || fail "Failed to reload PHP-FPM"
If a given PHP version is installed without a matching php*-fpm unit, deployments will hard-fail here. That may be acceptable given your server:install flow, but if you ever support CLI-only PHP installs, you might want to downgrade this to a warning (similar to how site-add.sh handles optional restarts).

Also applies to: 249-266, 284-301, 308-311, 341-357, 369-374
app/Console/Site/SiteDeployCommand.php (2)

41-49: Command options cover expected deployment knobs

domain, keep-releases, and yes map cleanly to the underlying playbook parameters and UX. The description on keep-releases matches DEFAULT_KEEP_RELEASES = 5; just ensure any future change to the constant is reflected in this help text.

235-364: Multiple single-use helpers vs. guideline about inlining

displayDeploymentSummary(), resolveKeepReleases(), resolvePhpVersion(), and checkRemoteHooksExist() are all currently single-use private helpers. Per the PHP guidelines you shared (“Eliminate single-use methods: inline if a method is called only once”), you could inline some of this logic back into execute() to reduce indirection.

Given the size and distinct responsibilities of these blocks, I’d personally keep them extracted for readability/testability, but if you want to strictly follow the guideline, displayDeploymentSummary() and checkRemoteHooksExist() are the easiest candidates to inline with minimal impact.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2718b55 and d7d13c8.

📒 Files selected for processing (11)

app/Console/Server/ServerLogsCommand.php (9 hunks)
app/Console/Site/SiteDeployCommand.php (1 hunks)
app/Console/Site/SiteSharedPushCommand.php (2 hunks)
app/SymfonyApp.php (2 hunks)
playbooks/helpers.sh (5 hunks)
playbooks/install-php.sh (1 hunks)
playbooks/site-add.sh (4 hunks)
playbooks/site-deploy.sh (1 hunks)
playbooks/site-link-shared.sh (1 hunks)
scaffolds/hooks/1-building.sh (1 hunks)
scaffolds/hooks/2-releasing.sh (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**/*.php

📄 CodeRabbit inference engine (.cursor/rules/00-main.mdc)

**/*.php: Eliminate single-use methods: inline if a method is called only once
Cache computed values: initialize expensive calculations in the constructor
Avoid method call overhead: prefer direct property access when appropriate

Files:

app/Console/Site/SiteSharedPushCommand.php
app/SymfonyApp.php
app/Console/Server/ServerLogsCommand.php
app/Console/Site/SiteDeployCommand.php

🧠 Learnings (12)

📚 Learning: 2025-09-21T08:52:38.782Z

Learnt from: CR
Repo: deployer-plus/deployer-php PR: 0
File: .cursor/rules/00-main.mdc:0-0
Timestamp: 2025-09-21T08:52:38.782Z
Learning: Applies to **/{composer.json,package.json} : Check composer.json and package.json for installed packages before starting any task

Applied to files:

scaffolds/hooks/1-building.sh
playbooks/install-php.sh

📚 Learning: 2025-10-24T19:58:34.899Z

Learnt from: CR
Repo: bigpixelrocket/deployer-php PR: 0
File: .cursor/rules/00-main.mdc:0-0
Timestamp: 2025-10-24T19:58:34.899Z
Learning: Applies to {composer.json,package.json} : Check composer.json and package.json for installed packages before any task

Applied to files:

scaffolds/hooks/1-building.sh
playbooks/install-php.sh

📚 Learning: 2025-09-21T08:52:38.782Z

Learnt from: CR
Repo: deployer-plus/deployer-php PR: 0
File: .cursor/rules/00-main.mdc:0-0
Timestamp: 2025-09-21T08:52:38.782Z
Learning: Applies to **/{composer.json,package.json} : Plan implementation using features supported by the major versions specified in composer.json and package.json

Applied to files:

scaffolds/hooks/1-building.sh