Add logs tasks, update docs

studio24 · May 2, 2024 · 176e711 · 176e711
1 parent e10d264
commit 176e711
Show file tree

Hide file tree

Showing 10 changed files with 357 additions and 49 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -20,13 +20,22 @@ This package contains [Deployer](https://deployer.org/) recipes used to help dep
 * Symfony
 * WordPress
 
-## Tasks
+## Deployment tasks
 
 * [build-summary](tasks/build-summary.md) - create a `_build_summary.json` file to record deployment info
-* [check-branch](tasks/check-branch.md) - ensure only default branch (main/master) is deployed to production
-* [check-ssh](tasks/check-ssh.md) - check SSH connection to remote server
+* [check:branch](tasks/check-branch.md) - ensure only default branch (main/master) is deployed to production
 * [confirm-continue](tasks/confirm-continue.md) - ask confirmation from user before continuing with deployment
-* [display-disk-space](tasks/display-disk-space.md) - display server disk usage prior to deployment
-* [show-summary](tasks/show-summary.md) - display a summary of the current deployment info
+* [check:disk-space](tasks/display-disk-space.md) - display server disk usage prior to deployment
+* [show](tasks/show-summary.md) - display a summary of the current deployment info
 * [sync](tasks/sync.md) - sync files or folders from the remote host to local development
 * [vendors-subpath](tasks/vendors-subpath.md) - Run composer install in a sub-path
+
+## Utility tasks
+
+* [check-ssh](tasks/check-ssh.md) - check SSH connection to remote server
+* [logs:list]
+* [logs:view]
+* [logs:search]
+* [logs:download]
+* [show](tasks/show-summary.md) - display a summary of the current deployment info 
+* [sync](tasks/sync.md) - sync files or folders from the remote host to local development
diff --git a/docs/tasks/check-branch.md b/docs/tasks/check-branch.md
@@ -15,7 +15,7 @@ No configuration required
 
 ## Tasks
 
-- `check-branch` – checks which stage and branch you are trying to deploy to. Ensures that non main branches deployed to production have to be forced.
+- `check:branch` – checks which stage and branch you are trying to deploy to. Ensures that non main branches deployed to production have to be forced.
 
 ## Usage
 

diff --git a/docs/tasks/display-disk-space.md b/docs/tasks/display-disk-space.md
@@ -6,15 +6,23 @@ Displays the disk usage of the remote server in the terminal
 Either [install all Studio 24 tasks](../installation.md) or install this individual task by adding to your `deploy.php`:
 
 ```php
-require 'vendor/studio24/deployer-recipes/tasks/display-disk-space.php';
+require 'vendor/studio24/deployer-recipes/tasks/check-disk-space.php';
 ```
 
 ## Configuration
-No configuration required
+If you set the filesystem mount this check can review disk capacity and warn if it is too low.
+
+```
+# AWS
+set('disk_space_filesystem', '/data');
+
+# Mythic Beasts
+set('disk_space_filesystem', '/');
+```
 
 ## Tasks
 
-- `display-disk-space` – checks the disk usage of the target server and displays the results
+- `check:disk-space` – checks the disk usage of the target server and displays the results
 
 ## Usage
 
@@ -27,3 +35,11 @@ Filesystem      Size  Used Avail Use% Mounted on
 /dev/nvme0n1p1  8.0G  4.0G  4.1G  50% /
 /dev/nvme1n1     40G   27G   14G  68% /data
 ```
+
+If you have set `disk_space_filesystem` a warning is displayed if the disk capacity is too low:
+
+```
+[production] Server disk space is almost full: 94% used
+[production] Filesystem      Size  Used Avail Use% Mounted on
+/dev/nvme1n1     40G   38G  2.8G  94% /data
+```
diff --git a/docs/tasks/logs.md b/docs/tasks/logs.md
@@ -0,0 +1,91 @@
+# Logs
+
+Tasks to help you interrogate log files.
+
+## Tasks
+
+- [logs:list](#logslist) – List available log files
+- [logs:view](#logsview) – View a log file
+- [logs:search](#logssearch) - Search a log file
+- [logs:download](#logsdownload) - Download a log file
+
+## Installation
+
+Either [install all Studio 24 tasks](../installation.md) or install this individual task by adding to your `deploy.php`:
+
+```php
+require 'vendor/studio24/deployer-recipes/tasks/logs.php';
+```
+
+## Configuration
+Ensure you have set the `log_files` configuration variable in your `deploy.php` file. This can be a string (multiple values separated by a commma) or an array of log files.
+
+E.g. 
+
+```
+set('log_files', '/data/logs/staging.studio24.net.access.log /data/logs/staging.studio24.net.error.log')
+```
+
+or:
+
+```
+set('log_files', [
+    '/data/logs/staging.studio24.net.access.log',
+    '/data/logs/staging.studio24.net.error.log',
+    'storage/logs/*.log',
+])
+```
+
+Please note by using this task you can specify `log_files` as a string or array safely, and it will continue to work with other Deployer log tasks (such as `dep log:app`).
+
+## Usage
+
+### logs:list
+
+List available log files.
+
+Example:
+
+```
+dep logs:list production
+```
+
+
+### logs:view
+
+View a log file, options include:
+
+* `--logfile=[LOGFILE]` The log file to view - you are asked to choose a file if you don't set this option
+* `--lines=[LINES]` Number of lines to display - defaults to 20, 0 returns all lines
+
+Example:
+
+```
+dep logs:view production
+```
+
+### logs:search
+
+Return matching lines from a log file, options include:
+
+* `--logfile=[LOGFILE]` The log file to search - you are asked to choose a file if you don't set this option
+* `--search=[SEARCH]` Only return lines that match the search string
+* `--lines=[LINES]` Number of lines to display - defaults to 20, 0 returns all lines
+
+Example:
+
+```
+dep logs:search production
+```
+
+### logs:download
+
+Download a logfile to your local computer, options include:
+
+* `--logfile=[LOGFILE]` The log file to download - you are asked to choose a file if you don't set this option 
+
+Example:
+
+```
+dep logs:download production
+```
diff --git a/docs/tasks/show-summary.md b/docs/tasks/show-summary.md
@@ -15,19 +15,19 @@ No configuration is required.
 
 ## Tasks
 
-- `show-summary` – retrieves current deployment info and displays in the terminal
+- `show` – retrieves current deployment info and displays in the terminal
 
 ## Usage
 
 Run on any environment to display current deploy information   
 
 ```
-dep show-summary <environment>
+dep show <environment>
 ```  
 
 eg:
 ```
-dep show-summary production
+dep show production
 ```  
 
 This returns a response detailing what is deployed to production.

diff --git a/recipe/common.php b/recipe/common.php
@@ -3,6 +3,9 @@
 namespace Deployer;
 
 // Require all Studio 24 Deployer tasks
+use Studio24\DeployerRecipes\Command\LogsSearchCommand;
+
+// Add custom deployment tasks
 require_once __DIR__ . '/../tasks/sync.php';
 require_once __DIR__ . '/../tasks/build-summary.php';
 require_once __DIR__ . '/../tasks/show-summary.php';
@@ -11,7 +14,7 @@
 require_once __DIR__ . '/../tasks/confirm-continue.php';
 require_once __DIR__ . '/../tasks/vendors-subpath.php';
 require_once __DIR__ . '/../tasks/ssh-check.php';
-require_once __DIR__ . '/../tasks/log-files.php';
+require_once __DIR__ . '/../tasks/logs.php';
 
 // Default deployment and HTTP users
 set('remote_user', 'deploy');

diff --git a/recipe/craftcms.php b/recipe/craftcms.php
@@ -43,7 +43,7 @@
 desc('Craft storage: reset storage permissions');
 task('craft:storage', function () {
     writeln('Updating storage directory permissions');
-    run('deploy:writable');
+    invoke('deploy:writable');
 });
 
 desc('Runs pending Craft CMS migrations and applies pending project config changes');

diff --git a/tasks/check-disk-space.php b/tasks/check-disk-space.php
@@ -13,7 +13,7 @@
 
 desc('Display server disk usage prior to deployment');
 task('check:disk-space', function () {
-    $filesystem = get('', '');
+    $filesystem = get('disk_space_filesystem', '');
     $threshold = (int) get('disk_space_threshold', 80);
 
     if (!empty($filesystem)) {

diff --git a/tasks/log-files.php b/tasks/log-files.php