diff --git a/docs/contrib/bugsnag.md b/docs/contrib/bugsnag.md index b0e4576bc..901dad95c 100644 --- a/docs/contrib/bugsnag.md +++ b/docs/contrib/bugsnag.md @@ -12,6 +12,18 @@ require 'contrib/bugsnag.php'; +## Configuration +- *bugsnag_api_key* – the API Key associated with the project. Informs Bugsnag which project has been deployed. This is the only required field. +- *bugsnag_provider* – the name of your source control provider. Required when repository is supplied and only for on-premise services. +- *bugsnag_app_version* – the app version of the code you are currently deploying. Only set this if you tag your releases with semantic version numbers and deploy infrequently. (Optional.) +## Usage +Since you should only notify Bugsnag of a successful deployment, the `bugsnag:notify` task should be executed right at the end. +```php +after('deploy', 'bugsnag:notify'); +``` + + + ## Tasks ### bugsnag:notify diff --git a/docs/contrib/cachetool.md b/docs/contrib/cachetool.md index 0ff9dcc08..e87461699 100644 --- a/docs/contrib/cachetool.md +++ b/docs/contrib/cachetool.md @@ -11,11 +11,77 @@ require 'contrib/cachetool.php'; [Source](/contrib/cachetool.php) + +## Configuration +- **cachetool** *(optional)*: accepts a *string* or an *array* of strings with the unix socket or ip address to php-fpm. If `cachetool` is not given, then the application will look for a configuration file. The file must be named .cachetool.yml or .cachetool.yaml. CacheTool will look for this file on the current directory and in any parent directory until it finds one. If the paths above fail it will try to load /etc/cachetool.yml or /etc/cachetool.yaml configuration file. + ```php + set('cachetool', '/var/run/php-fpm.sock'); + // or + set('cachetool', '127.0.0.1:9000'); + // or + set('cachetool', ['/var/run/php-fpm.sock', '/var/run/php-fpm-other.sock']); + ``` +You can also specify different cachetool settings for each host: +```php +host('staging') + ->set('cachetool', '127.0.0.1:9000'); +host('production') + ->set('cachetool', '/var/run/php-fpm.sock'); +``` +By default, if no `cachetool` parameter is provided, this recipe will fallback to the global setting. +If your deployment user does not have permission to access the php-fpm.sock, you can alternatively use +the web adapter that creates a temporary php file and makes a web request to it with a configuration like +```php +set('cachetool_args', '--web --web-path=./public --web-url=https://{{hostname}}'); +``` +## Usage +Since APCu and OPcache deal with compiling and caching files, they should be executed right after the symlink is created for the new release: +```php +after('deploy:symlink', 'cachetool:clear:opcache'); +or +after('deploy:symlink', 'cachetool:clear:apcu'); +``` +## Read more +Read more information about cachetool on the website: +http://gordalina.github.io/cachetool/ + + ## Configuration ### cachetool [Source](https://github.com/deployphp/deployer/blob/master/contrib/cachetool.php#L51) - +## Configuration +- **cachetool** *(optional)*: accepts a *string* or an *array* of strings with the unix socket or ip address to php-fpm. If `cachetool` is not given, then the application will look for a configuration file. The file must be named .cachetool.yml or .cachetool.yaml. CacheTool will look for this file on the current directory and in any parent directory until it finds one. If the paths above fail it will try to load /etc/cachetool.yml or /etc/cachetool.yaml configuration file. + ```php + set('cachetool', '/var/run/php-fpm.sock'); + // or + set('cachetool', '127.0.0.1:9000'); + // or + set('cachetool', ['/var/run/php-fpm.sock', '/var/run/php-fpm-other.sock']); + ``` +You can also specify different cachetool settings for each host: +```php +host('staging') + ->set('cachetool', '127.0.0.1:9000'); +host('production') + ->set('cachetool', '/var/run/php-fpm.sock'); +``` +By default, if no `cachetool` parameter is provided, this recipe will fallback to the global setting. +If your deployment user does not have permission to access the php-fpm.sock, you can alternatively use +the web adapter that creates a temporary php file and makes a web request to it with a configuration like +```php +set('cachetool_args', '--web --web-path=./public --web-url=https://{{hostname}}'); +``` +## Usage +Since APCu and OPcache deal with compiling and caching files, they should be executed right after the symlink is created for the new release: +```php +after('deploy:symlink', 'cachetool:clear:opcache'); +or +after('deploy:symlink', 'cachetool:clear:apcu'); +``` +## Read more +Read more information about cachetool on the website: +http://gordalina.github.io/cachetool/ diff --git a/docs/contrib/chatwork.md b/docs/contrib/chatwork.md index cefa95b8c..8bcefed84 100644 --- a/docs/contrib/chatwork.md +++ b/docs/contrib/chatwork.md @@ -11,6 +11,77 @@ require 'contrib/chatwork.php'; [Source](/contrib/chatwork.php) + +# Chatwork Recipe +## Installing + 1. Create chatwork account by any manual in the internet + 2. Take chatwork token (Like: b29a700e2d15bef3f26ae6a5c142d1ea) and set `chatwork_token` parameter + 3. Take chatwork room id from url after clicked on the room, and set `chatwork_room_id` parameter + 4. If you want, you can edit `chatwork_notify_text`, `chatwork_success_text` or `chatwork_failure_text` + 5. Require chatwork recipe in your `deploy.php` file +```php +# https://deployer.org/recipes.html +require 'recipe/chatwork.php'; +``` +Add hook on deploy: +```php +before('deploy', 'chatwork:notify'); +``` +## Configuration +- `chatwork_token` – chatwork bot token, **required** +- `chatwork_room_id` — chatwork room to push messages to **required** +- `chatwork_notify_text` – notification message template + ``` + [info] + [title](*) Deployment Status: Deploying[/title] + Repo: {{repository}} + Branch: {{branch}} + Server: {{hostname}} + Release Path: {{release_path}} + Current Path: {{current_path}} + [/info] + ``` +- `chatwork_success_text` – success template, default: + ``` + [info] + [title](*) Deployment Status: Successfully[/title] + Repo: {{repository}} + Branch: {{branch}} + Server: {{hostname}} + Release Path: {{release_path}} + Current Path: {{current_path}} + [/info]" + ``` +- `chatwork_failure_text` – failure template, default: + ``` + [info] + [title](*) Deployment Status: Failed[/title] + Repo: {{repository}} + Branch: {{branch}} + Server: {{hostname}} + Release Path: {{release_path}} + Current Path: {{current_path}} + [/info]" + ``` +## Tasks +- `chatwork:notify` – send message to chatwork +- `chatwork:notify:success` – send success message to chatwork +- `chatwork:notify:failure` – send failure message to chatwork +## Usage +If you want to notify only about beginning of deployment add this line only: +```php +before('deploy', 'chatwork:notify'); +``` +If you want to notify about successful end of deployment add this too: +```php +after('success', 'chatwork:notify:success'); +``` +If you want to notify about failed deployment add this too: +```php +after('deploy:failed', 'chatwork:notify:failure'); +``` + + ## Configuration ### chatwork_token [Source](https://github.com/deployphp/deployer/blob/master/contrib/chatwork.php#L93) diff --git a/docs/contrib/cimonitor.md b/docs/contrib/cimonitor.md index f1cf77601..cfaf3eb0f 100644 --- a/docs/contrib/cimonitor.md +++ b/docs/contrib/cimonitor.md @@ -11,6 +11,49 @@ require 'contrib/cimonitor.php'; [Source](/contrib/cimonitor.php) + +Monitor your deployments on [CIMonitor](https://github.com/CIMonitor/CIMonitor). +![CIMonitorGif](https://www.steefmin.xyz/deployer-example.gif) +Add tasks on deploy: +```php +before('deploy', 'cimonitor:notify'); +after('deploy:success', 'cimonitor:notify:success'); +after('deploy:failed', 'cimonitor:notify:failure'); +``` +## Configuration +- `cimonitor_webhook` – CIMonitor server webhook url, **required** + ``` + set('cimonitor_webhook', 'https://cimonitor.enrise.com/webhook/deployer'); + ``` +- `cimonitor_title` – the title of application, default the username\reponame combination from `{{repository}}` + ``` + set('cimonitor_title', ''); + ``` +- `cimonitor_user` – User object with name and email, default gets information from `git config` + ``` + set('cimonitor_user', function () { + return [ + 'name' => 'John Doe', + 'email' => 'john@enrise.com', + ]; + }); + ``` +Various cimonitor statusses are set, in case you want to change these yourselves. See the [CIMonitor documentation](https://cimonitor.readthedocs.io/en/latest/) for the usages of different states. +## Usage +If you want to notify only about beginning of deployment add this line only: +```php +before('deploy', 'cimonitor:notify'); +``` +If you want to notify about successful end of deployment add this too: +```php +after('deploy:success', 'cimonitor:notify:success'); +``` +If you want to notify about failed deployment add this too: +```php +after('deploy:failed', 'cimonitor:notify:failure'); +``` + + ## Configuration ### cimonitor_title [Source](https://github.com/deployphp/deployer/blob/master/contrib/cimonitor.php#L64) diff --git a/docs/contrib/cloudflare.md b/docs/contrib/cloudflare.md index 6413167ee..e9b2b1404 100644 --- a/docs/contrib/cloudflare.md +++ b/docs/contrib/cloudflare.md @@ -12,6 +12,20 @@ require 'contrib/cloudflare.php'; +### Configuration +- `cloudflare` – array with configuration for cloudflare + - `service_key` – Cloudflare Service Key. If this is not provided, use api_key and email. + - `api_key` – Cloudflare API key generated on the "My Account" page. + - `email` – Cloudflare Email address associated with your account. + - `api_token` – Cloudflare API Token generated on the "My Account" page. + - `domain` – The domain you want to clear (optional if zone_id is provided). + - `zone_id` – Cloudflare Zone ID (optional). +### Usage +Since the website should be built and some load is likely about to be applied to your server, this should be one of, +if not the, last tasks before cleanup + + + ## Tasks ### deploy:cloudflare @@ -19,6 +33,16 @@ require 'contrib/cloudflare.php'; Clears Cloudflare Cache. - +### Configuration +- `cloudflare` – array with configuration for cloudflare + - `service_key` – Cloudflare Service Key. If this is not provided, use api_key and email. + - `api_key` – Cloudflare API key generated on the "My Account" page. + - `email` – Cloudflare Email address associated with your account. + - `api_token` – Cloudflare API Token generated on the "My Account" page. + - `domain` – The domain you want to clear (optional if zone_id is provided). + - `zone_id` – Cloudflare Zone ID (optional). +### Usage +Since the website should be built and some load is likely about to be applied to your server, this should be one of, +if not the, last tasks before cleanup diff --git a/docs/contrib/cpanel.md b/docs/contrib/cpanel.md index 77caba79d..8a59d7318 100644 --- a/docs/contrib/cpanel.md +++ b/docs/contrib/cpanel.md @@ -12,6 +12,107 @@ require 'contrib/cpanel.php'; +### Description +This is a recipe that uses the [cPanel 2 API](https://documentation.cPanel.net/display/DD/Guide+to+cPanel+API+2). +Unfortunately the [UAPI](https://documentation.cPanel.net/display/DD/Guide+to+UAPI) that is recommended does not have support for creating addon domains. +The main idea behind is for staging purposes but I guess you can use it for other interesting concepts. +The idea is, every branch possibly has its own staging domain/subdomain (staging-neat-feature.project.com) and database db_neat-feature_project so it can be tested. +This recipe can make the domain/subdomain and database creation part of the deployment process so you don't have to manually create them through an interface. +### Configuration +The example uses a .env file and Dotenv for configuration, but you can set the parameters as you wish +``` +set('cpanel', [ + 'host' => getenv('CPANEL_HOST'), + 'port' => getenv('CPANEL_PORT'), + 'username' => getenv('CPANEL_USERNAME'), + 'auth_type' => getenv('CPANEL_AUTH_TYPE'), + 'token' => getenv('CPANEL_TOKEN'), + 'user' => getenv('CPANEL_USER'), + 'db_user' => getenv('CPANEL_DB_USER'), + 'db_user_privileges' => getenv('CPANEL_DB_PRIVILEGES'), + 'timeout' => 500, + 'allowInStage' => ['staging', 'beta', 'alpha'], + 'create_domain_format' => '%s-%s-%s', + 'create_domain_values' => ['staging', 'master', get('application')], + 'subdomain_prefix' => substr(md5(get('application')), 0,4) . '-', + 'subdomain_suffix' => getenv('SUDOMAIN_SUFFIX'), + 'create_db_format' => '%s_%s-%s-%s', + 'create_db_values' => ['apps', 'staging','master', get('application')], +]); +``` +- `cpanel` – array with configuration for cPanel + - `username` – WHM account + - `user` – cPanel account that you want in charge of the domain + - `token` – WHM API token + - `create_domain_format` – Format for name creation of domain + - `create_domain_values` – The actual value reference for naming + - `subdomain_prefix` – cPanel has a weird way of dealing with addons and subdomains, you cannot create 2 addons with the same subdomain, so you need to change it in some way, example uses first 4 chars of md5(app_name) + - `subdomain_suffix` – cPanel has a weird way of dealing with addons and subdomains, so the suffix needs to be your main domain for that account for deletion purposes + - `addondir` – addon dir is different from the deploy path because cPanel "injects" /home/user/ into the path, so tilde cannot be used + - `allowInStage` – Define the stages that cPanel recipe actions are allowed in +#### .env file example +``` +CPANEL_HOST=xxx.xxx.xxx.xxx +CPANEL_PORT=2087 +CPANEL_USERNAME=root +CPANEL_TOKEN=xxxx +CPANEL_USER=xxx +CPANEL_AUTH_TYPE=hash +CPANEL_DB_USER=db_user +CPANEL_DB_PRIVILEGES="ALL PRIVILEGES" +SUDOMAIN_SUFFIX=.mymaindomain.com +``` +### Tasks +- `cpanel:createaddondomain` Creates an addon domain +- `cpanel:deleteaddondomain` Removes an addon domain +- `cpanel:createdb` Creates a new database +### Usage +A complete example with configs, staging and deployment +``` +load(); // this is used just so an .env file can be used for credentials +require 'cpanel.php'; +Project name +set('application', 'myproject.com'); +Project repository +set('repository', 'git@github.com:myorg/myproject.com'); +set('cpanel', [ + 'host' => getenv('CPANEL_HOST'), + 'port' => getenv('CPANEL_PORT'), + 'username' => getenv('CPANEL_USERNAME'), + 'auth_type' => getenv('CPANEL_AUTH_TYPE'), + 'token' => getenv('CPANEL_TOKEN'), + 'user' => getenv('CPANEL_USER'), + 'db_user' => getenv('CPANEL_DB_USER'), + 'db_user_privileges' => getenv('CPANEL_DB_PRIVILEGES'), + 'timeout' => 500, + 'allowInStage' => ['staging', 'beta', 'alpha'], + 'create_domain_format' => '%s-%s-%s', + 'create_domain_values' => ['staging', 'master', get('application')], + 'subdomain_prefix' => substr(md5(get('application')), 0,4) . '-', + 'subdomain_suffix' => getenv('SUDOMAIN_SUFFIX'), + 'create_db_format' => '%s_%s-%s-%s', + 'create_db_values' => ['apps', 'staging','master', get('application')], +]); +host('myproject.com') + ->stage('staging') + ->set('cpanel_createdb', vsprintf(get('cpanel')['create_db_format'], get('cpanel')['create_db_values'])) + ->set('branch', 'dev-branch') + ->set('deploy_path', '~/staging/' . vsprintf(get('cpanel')['create_domain_format'], get('cpanel')['create_domain_values'])) + ->set('addondir', 'staging/' . vsprintf(get('cpanel')['create_domain_format'], get('cpanel')['create_domain_values'])); +Tasks +task('build', function () { + run('cd {{release_path}} && build'); +}); +after('deploy:prepare', 'cpanel:createaddondomain'); +after('deploy:prepare', 'cpanel:createdb'); +``` + + + ## Tasks ### cpanel:createdb diff --git a/docs/contrib/crontab.md b/docs/contrib/crontab.md index 45017d838..f7395cf88 100644 --- a/docs/contrib/crontab.md +++ b/docs/contrib/crontab.md @@ -11,10 +11,39 @@ require 'contrib/crontab.php'; [Source](/contrib/crontab.php) + +Recipe for adding crontab jobs. +This recipe creates a new section in the crontab file with the configured jobs. +The section is identified by the *crontab:identifier* variable, by default the application name. +## Configuration +- *crontab:jobs* - An array of strings with crontab lines. +## Usage +```php +require 'contrib/crontab.php'; +after('deploy:success', 'crontab:sync'); +add('crontab:jobs', [ + '* * * * * cd {{current_path}} && {{bin/php}} artisan schedule:run >> /dev/null 2>&1', +]); +``` + + ## Configuration ### bin/crontab [Source](https://github.com/deployphp/deployer/blob/master/contrib/crontab.php#L28) +Recipe for adding crontab jobs. +This recipe creates a new section in the crontab file with the configured jobs. +The section is identified by the *crontab:identifier* variable, by default the application name. +## Configuration +- *crontab:jobs* - An array of strings with crontab lines. +## Usage +```php +require 'contrib/crontab.php'; +after('deploy:success', 'crontab:sync'); +add('crontab:jobs', [ + '* * * * * cd {{current_path}} && {{bin/php}} artisan schedule:run >> /dev/null 2>&1', +]); +``` Get path to bin ```php title="Default value" diff --git a/docs/contrib/directadmin.md b/docs/contrib/directadmin.md index 6936f7971..21089cf24 100644 --- a/docs/contrib/directadmin.md +++ b/docs/contrib/directadmin.md @@ -12,6 +12,24 @@ require 'contrib/directadmin.php'; +### Configuration +- `directadmin` – array with configuration for DirectAdmin + - `host` – DirectAdmin host + - `port` – DirectAdmin port (default: 2222, not required) + - `scheme` – DirectAdmin scheme (default: http, not required) + - `username` – DirectAdmin username + - `password` – DirectAdmin password (it is recommended to use login keys!) + - `db_user` – Database username (required when using directadmin:createdb or directadmin:deletedb) + - `db_name` – Database namse (required when using directadmin:createdb) + - `db_password` – Database password (required when using directadmin:createdb) + - `domain_name` – Domain to create, delete or edit (required when using directadmin:createdomain, directadmin:deletedomain, directadmin:symlink-private-html or directadmin:php-version) + - `domain_ssl` – Enable SSL, options: ON/OFF, default: ON (optional when using directadmin:createdb) + - `domain_cgi` – Enable CGI, options: ON/OFF, default: ON (optional when using directadmin:createdb) + - `domain_php` – Enable PHP, options: ON/OFF, default: ON (optional when using directadmin:createdb) + - `domain_php_version` – Domain PHP Version, default: 1 (required when using directadmin:php-version) + + + ## Tasks ### directadmin:createdb diff --git a/docs/contrib/discord.md b/docs/contrib/discord.md index d7ddcd0c4..0f75ea830 100644 --- a/docs/contrib/discord.md +++ b/docs/contrib/discord.md @@ -11,6 +11,41 @@ require 'contrib/discord.php'; [Source](/contrib/discord.php) + +## Installing +Add hook on deploy: +```php +before('deploy', 'discord:notify'); +``` +## Configuration +- `discord_channel` – Discord channel ID, **required** +- `discord_token` – Discord channel token, **required** +- `discord_notify_text` – notification message template, markdown supported, default: + ```markdown + :​information_source: **{{user}}** is deploying branch `{{branch}}` to _{{target}}_ + ``` +- `discord_success_text` – success template, default: + ```markdown + :​white_check_mark: Branch `{{branch}}` deployed to _{{target}}_ successfully + ``` +- `discord_failure_text` – failure template, default: + ```markdown + :​no_entry_sign: Branch `{{branch}}` has failed to deploy to _{{target}}_ +## Usage +If you want to notify only about beginning of deployment add this line only: +```php +before('deploy', 'discord:notify'); +``` +If you want to notify about successful end of deployment add this too: +```php +after('deploy:success', 'discord:notify:success'); +``` +If you want to notify about failed deployment add this too: +```php +after('deploy:failed', 'discord:notify:failure'); +``` + + ## Configuration ### discord_webhook [Source](https://github.com/deployphp/deployer/blob/master/contrib/discord.php#L54) diff --git a/docs/contrib/grafana.md b/docs/contrib/grafana.md index 9fcb7bb32..d79b6147c 100644 --- a/docs/contrib/grafana.md +++ b/docs/contrib/grafana.md @@ -12,6 +12,28 @@ require 'contrib/grafana.php'; +## Configuration options +- **url** *(required)*: the URL to the creates annotation api endpoint. +- **token** *(required)*: authentication token. Can be created at Grafana Console. +- **time** *(optional)* – set deploy time of annotation. specify epoch milliseconds. (Defaults is set to the current time in epoch milliseconds.) +- **tags** *(optional)* – set tag of annotation. +- **text** *(optional)* – set text of annotation. (Defaults is set to "Deployed " + git log -n 1 --format="%h") +```php +deploy.php +set('grafana', [ + 'token' => 'eyJrIj...', + 'url' => 'http://grafana/api/annotations', + 'tags' => ['deploy', 'production'], +]); +``` +## Usage +If you want to create annotation about successful end of deployment. +```php +after('deploy:success', 'grafana:annotation'); +``` + + + ## Tasks ### grafana:annotation diff --git a/docs/contrib/hangouts.md b/docs/contrib/hangouts.md index b93aeacd2..64f0ee6ca 100644 --- a/docs/contrib/hangouts.md +++ b/docs/contrib/hangouts.md @@ -11,6 +11,33 @@ require 'contrib/hangouts.php'; [Source](/contrib/hangouts.php) + +Add hook on deploy: +```php +before('deploy', 'chat:notify'); +``` +## Configuration +- `chat_webhook` – chat incoming webhook url, **required** +- `chat_title` – the title of your notification card, default `{{application}}` +- `chat_subtitle` – the subtitle of your card, default `{{hostname}}` +- `chat_favicon` – an image for the header of your card, default `http://{{hostname}}/favicon.png` +- `chat_line1` – first line of the text in your card, default: `{{branch}}` +- `chat_line2` – second line of the text in your card, default: `{{stage}}` +## Usage +If you want to notify only about beginning of deployment add this line only: +```php +before('deploy', 'chat:notify'); +``` +If you want to notify about successful end of deployment add this too: +```php +after('deploy:success', 'chat:notify:success'); +``` +If you want to notify about failed deployment add this too: +```php +after('deploy:failed', 'chat:notify:failure'); +``` + + ## Configuration ### chat_title [Source](https://github.com/deployphp/deployer/blob/master/contrib/hangouts.php#L46) diff --git a/docs/contrib/hipchat.md b/docs/contrib/hipchat.md index 3b80b0a5f..2d1c2aa41 100644 --- a/docs/contrib/hipchat.md +++ b/docs/contrib/hipchat.md @@ -11,6 +11,21 @@ require 'contrib/hipchat.php'; [Source](/contrib/hipchat.php) + +## Configuration +- `hipchat_token` – Hipchat V1 auth token +- `hipchat_room_id` – Room ID or name +- `hipchat_message` – Deploy message, default is `_{{user}}_ deploying `{{branch}}` to *{{target}}*` +- `hipchat_from` – Default to target +- `hipchat_color` – Message color, default is **green** +- `hipchat_url` – The URL to the message endpoint, default is https://api.hipchat.com/v1/rooms/message +## Usage +Since you should only notify Hipchat room of a successful deployment, the `hipchat:notify` task should be executed right at the end. +```php +after('deploy', 'hipchat:notify'); +``` + + ## Configuration ### hipchat_color [Source](https://github.com/deployphp/deployer/blob/master/contrib/hipchat.php#L26) diff --git a/docs/contrib/ispmanager.md b/docs/contrib/ispmanager.md index d58fbe6b6..00cfe80df 100644 --- a/docs/contrib/ispmanager.md +++ b/docs/contrib/ispmanager.md @@ -11,6 +11,10 @@ require 'contrib/ispmanager.php'; [Source](/contrib/ispmanager.php) + +This recipe for work with ISPManager Lite panel by API. + + ## Configuration ### ispmanager_owner [Source](https://github.com/deployphp/deployer/blob/master/contrib/ispmanager.php#L11) diff --git a/docs/contrib/mattermost.md b/docs/contrib/mattermost.md index 7d6258ac7..9481ac7e5 100644 --- a/docs/contrib/mattermost.md +++ b/docs/contrib/mattermost.md @@ -11,6 +11,60 @@ require 'contrib/mattermost.php'; [Source](/contrib/mattermost.php) + +## Installing +Create a Mattermost incoming webhook, through the administration panel. +Add hook on deploy: +``` +before('deploy', 'mattermost:notify'); +``` +## Configuration + - `mattermost_webhook` - incoming mattermost webook **required** + ``` + set('mattermost_webook', 'https://{your-mattermost-site}/hooks/xxx-generatedkey-xxx'); + ``` + - `mattermost_channel` - overrides the channel the message posts in + ``` + set('mattermost_channel', 'town-square'); + ``` + - `mattermost_username` - overrides the username the message posts as + ``` + set('mattermost_username', 'deployer'); + ``` + - `mattermost_icon_url` - overrides the profile picture the message posts with + ``` + set('mattermost_icon_url', 'https://domain.com/your-icon.png'); + ``` + - `mattermost_text` - notification message + ``` + set('mattermost_text', '_{{user}}_ deploying `{{branch}}` to **{{target}}**'); + ``` + - `mattermost_success_text` – success template, default: + ``` + set('mattermost_success_text', 'Deploy to **{{target}}** successful {{mattermost_success_emoji}}'); + ``` + - `mattermost_failure_text` – failure template, default: + ``` + set('mattermost_failure_text', 'Deploy to **{{target}}** failed {{mattermost_failure_emoji}}'); + ``` + - `mattermost_success_emoji` – emoji added at the end of success text + - `mattermost_failure_emoji` – emoji added at the end of failure text + For detailed information about Mattermost hooks see: https://developers.mattermost.com/integrate/incoming-webhooks/ +## Usage +If you want to notify only about beginning of deployment add this line only: +```php +before('deploy', 'mattermost:notify'); +``` +If you want to notify about successful end of deployment add this too: +```php +after('deploy:success', 'mattermost:notify:success'); +``` +If you want to notify about failed deployment add this too: +```php +after('deploy:failed', 'mattermost:notify:failure'); +``` + + ## Configuration ### mattermost_webhook [Source](https://github.com/deployphp/deployer/blob/master/contrib/mattermost.php#L81) diff --git a/docs/contrib/ms-teams.md b/docs/contrib/ms-teams.md index 75dcbbd33..f2c0240cd 100644 --- a/docs/contrib/ms-teams.md +++ b/docs/contrib/ms-teams.md @@ -11,6 +11,66 @@ require 'contrib/ms-teams.php'; [Source](/contrib/ms-teams.php) + +## Installing +Require ms-teams recipe in your `deploy.php` file: +Setup: +1. Open MS Teams +2. Navigate to Teams section +3. Select existing or create new team +4. Select existing or create new channel +5. Hover over channel to get three dots, click, in menu select "Connectors" +6. Search for and configure "Incoming Webhook" +7. Confirm/create and copy your Webhook URL +8. Setup deploy.php + Add in header: +```php +require 'contrib/ms-teams.php'; +set('teams_webhook', 'https://outlook.office.com/webhook/...'); +``` +Add in content: +```php +before('deploy', 'teams:notify'); +after('deploy:success', 'teams:notify:success'); +after('deploy:failed', 'teams:notify:failure'); +``` +9.) Sip your coffee +## Configuration +- `teams_webhook` – teams incoming webhook url, **required** + ``` + set('teams_webhook', 'https://outlook.office.com/webhook/...'); + ``` +- `teams_title` – the title of application, default `{{application}}` +- `teams_text` – notification message template, markdown supported + ``` + set('teams_text', '_{{user}}_ deploying `{{branch}}` to *{{target}}*'); + ``` +- `teams_success_text` – success template, default: + ``` + set('teams_success_text', 'Deploy to *{{target}}* successful'); + ``` +- `teams_failure_text` – failure template, default: + ``` + set('teams_failure_text', 'Deploy to *{{target}}* failed'); + ``` +- `teams_color` – color's attachment +- `teams_success_color` – success color's attachment +- `teams_failure_color` – failure color's attachment +## Usage +If you want to notify only about beginning of deployment add this line only: +```php +before('deploy', 'teams:notify'); +``` +If you want to notify about successful end of deployment add this too: +```php +after('deploy:success', 'teams:notify:success'); +``` +If you want to notify about failed deployment add this too: +```php +after('deploy:failed', 'teams:notify:failure'); +``` + + ## Configuration ### teams_title [Source](https://github.com/deployphp/deployer/blob/master/contrib/ms-teams.php#L79) diff --git a/docs/contrib/newrelic.md b/docs/contrib/newrelic.md index 371919468..c0859584b 100644 --- a/docs/contrib/newrelic.md +++ b/docs/contrib/newrelic.md @@ -11,6 +11,19 @@ require 'contrib/newrelic.php'; [Source](/contrib/newrelic.php) + +## Configuration +- `newrelic_app_id` – newrelic's app id +- `newrelic_api_key` – newrelic's api key +- `newrelic_description` – message to send +- `newrelic_endpoint` – newrelic's REST API endpoint +## Usage +Since you should only notify New Relic of a successful deployment, the `newrelic:notify` task should be executed right at the end. +```php +after('deploy', 'newrelic:notify'); +``` + + ## Configuration ### newrelic_app_id [Source](https://github.com/deployphp/deployer/blob/master/contrib/newrelic.php#L24) diff --git a/docs/contrib/npm.md b/docs/contrib/npm.md index 4610930bf..5b5425143 100644 --- a/docs/contrib/npm.md +++ b/docs/contrib/npm.md @@ -11,11 +11,25 @@ require 'contrib/npm.php'; [Source](/contrib/npm.php) + +## Configuration +- `bin/npm` *(optional)*: set npm binary, automatically detected otherwise. +## Usage +```php +after('deploy:update_code', 'npm:install'); +``` + + ## Configuration ### bin/npm [Source](https://github.com/deployphp/deployer/blob/master/contrib/npm.php#L17) - +## Configuration +- `bin/npm` *(optional)*: set npm binary, automatically detected otherwise. +## Usage +```php +after('deploy:update_code', 'npm:install'); +``` ```php title="Default value" return which('npm'); diff --git a/docs/contrib/ntfy.md b/docs/contrib/ntfy.md index 3ea52749b..691d33d67 100644 --- a/docs/contrib/ntfy.md +++ b/docs/contrib/ntfy.md @@ -11,6 +11,78 @@ require 'contrib/ntfy.php'; [Source](/contrib/ntfy.php) + +## Installing +Require ntfy.sh recipe in your `deploy.php` file: +Setup: +1. Setup deploy.php + Add in header: +```php +require 'contrib/ntfy.php'; +set('ntfy_topic', 'ntfy.sh/mytopic'); +``` +Add in content: +```php +before('deploy', 'ntfy:notify'); +after('deploy:success', 'ntfy:notify:success'); +after('deploy:failed', 'ntfy:notify:failure'); +``` +9.) Sip your coffee +## Configuration +- `ntfy_server` – ntfy server url, default `ntfy.sh` + ``` + set('ntfy_server', 'ntfy.sh'); + ``` +- `ntfy_topic` – ntfy topic, **required** + ``` + set('ntfy_topic', 'mysecrettopic'); + ``` +- `ntfy_title` – the title of the message, default `{{application}}` +- `ntfy_text` – notification message template + ``` + set('ntfy_text', '_{{user}}_ deploying `{{branch}}` to *{{target}}*'); + ``` +- `ntfy_tags` – notification message tags / emojis (comma separated) + ``` + set('ntfy_tags', `information_source`); + ``` +- `ntfy_priority` – notification message priority (integer) + ``` + set('ntfy_priority', 5); + ``` +- `ntfy_success_text` – success template, default: + ``` + set('ntfy_success_text', 'Deploy to *{{target}}* successful'); + ``` +- `ntfy_success_tags` – success tags / emojis (comma separated) + ``` + set('ntfy_success_tags', `white_check_mark,champagne`); + ``` +- `ntfy_success_priority` – success notification message priority +- `ntfy_failure_text` – failure template, default: + ``` + set('ntfy_failure_text', 'Deploy to *{{target}}* failed'); + ``` +- `ntfy_failure_tags` – failure tags / emojis (comma separated) + ``` + set('ntfy_failure_tags', `warning,skull`); + ``` +- `ntfy_failure_priority` – failure notification message priority +## Usage +If you want to notify only about beginning of deployment add this line only: +```php +before('deploy', 'ntfy:notify'); +``` +If you want to notify about successful end of deployment add this too: +```php +after('deploy:success', 'ntfy:notify:success'); +``` +If you want to notify about failed deployment add this too: +```php +after('deploy:failed', 'ntfy:notify:failure'); +``` + + ## Configuration ### ntfy_server [Source](https://github.com/deployphp/deployer/blob/master/contrib/ntfy.php#L90) diff --git a/docs/contrib/phinx.md b/docs/contrib/phinx.md index 764ca2658..aa2a16d4e 100644 --- a/docs/contrib/phinx.md +++ b/docs/contrib/phinx.md @@ -11,10 +11,64 @@ require 'contrib/phinx.php'; [Source](/contrib/phinx.php) + +## Configuration options +All options are in the config parameter `phinx` specified as an array (instead of the `phinx_path` variable). +All parameters are *optional*, but you can specify them with a dictionary (to change all parameters) +or by deployer dot notation (to change one option). +### Phinx params +- `phinx.environment` +- `phinx.date` +- `phinx.configuration` N.B. current directory is the project directory +- `phinx.target` +- `phinx.seed` +- `phinx.parser` +- `phinx.remove-all` (pass empty string as value) +### Phinx path params +- `phinx_path` Specify phinx path (by default phinx is searched for in $PATH, ./vendor/bin and ~/.composer/vendor/bin) +### Example of usage +```php +$phinx_env_vars = [ + 'environment' => 'development', + 'configuration' => './migration/.phinx.yml', + 'target' => '20120103083322', + 'remove-all' => '', +]; +set('phinx_path', '/usr/local/phinx/bin/phinx'); +set('phinx', $phinx_env_vars); +after('cleanup', 'phinx:migrate'); +or set it for a specific server +host('dev') + ->user('user') + ->set('deploy_path', '/var/www') + ->set('phinx', $phinx_env_vars) + ->set('phinx_path', ''); +``` +## Suggested Usage +You can run all tasks before or after any +tasks (but you need to specify external configs for phinx). +If you use internal configs (which are in your project) you need +to run it after the `deploy:update_code` task is completed. +## Read more +For further reading see [phinx.org](https://phinx.org). Complete descriptions of all possible options can be found on the [commands page](http://docs.phinx.org/en/latest/commands.html). + + ## Configuration ### bin/phinx [Source](https://github.com/deployphp/deployer/blob/master/contrib/phinx.php#L81) +Phinx recipe for Deployer + +@author Alexey Boyko +@contributor Security-Database +@copyright 2016 Alexey Boyko +@license MIT https://github.com/deployphp/recipes/blob/master/LICENSE + +@link https://github.com/deployphp/recipes + +@see http://deployer.org +@see https://phinx.org + Path to Phinx :::info Autogenerated The value of this configuration is autogenerated on access. diff --git a/docs/contrib/php-fpm.md b/docs/contrib/php-fpm.md index 796ed1073..50367c5ee 100644 --- a/docs/contrib/php-fpm.md +++ b/docs/contrib/php-fpm.md @@ -11,10 +11,49 @@ require 'contrib/php-fpm.php'; [Source](/contrib/php-fpm.php) + +:::caution +Do **not** reload php-fpm. Some user requests could fail or not complete in the +process of reloading. +Instead, configure your server [properly](https://ï.at/avoid-php-fpm-reloading). If you're using Deployer's provision +recipe, it's already configured the right way and no php-fpm reload is needed. +::: +## Configuration +- `php_fpm_version` – The PHP-fpm version. For example: `8.0`. +- `php_fpm_service` – The full name of the PHP-fpm service. Defaults to `php{{php_fpm_version}}-fpm`. +- `php_fpm_command` – The command to run to reload PHP-fpm. Defaults to `sudo systemctl reload {{php_fpm_service}}`. +## Usage +Start by explicitely providing the current version of PHP-version using the `php_fpm_version`. +Alternatively, you may use any of the options above to configure how PHP-fpm should reload. +Then, add the `php-fpm:reload` task at the end of your deployments by using the `after` method like so. +```php +set('php_fpm_version', '8.0'); +after('deploy', 'php-fpm:reload'); +``` + + ## Configuration ### php_fpm_version [Source](https://github.com/deployphp/deployer/blob/master/contrib/php-fpm.php#L35) +:::caution +Do **not** reload php-fpm. Some user requests could fail or not complete in the +process of reloading. +Instead, configure your server [properly](https://ï.at/avoid-php-fpm-reloading). If you're using Deployer's provision +recipe, it's already configured the right way and no php-fpm reload is needed. +::: +## Configuration +- `php_fpm_version` – The PHP-fpm version. For example: `8.0`. +- `php_fpm_service` – The full name of the PHP-fpm service. Defaults to `php[php_fpm_version](/docs/contrib/php-fpm.md#php_fpm_version)-fpm`. +- `php_fpm_command` – The command to run to reload PHP-fpm. Defaults to `sudo systemctl reload [php_fpm_service](/docs/contrib/php-fpm.md#php_fpm_service)`. +## Usage +Start by explicitely providing the current version of PHP-version using the `php_fpm_version`. +Alternatively, you may use any of the options above to configure how PHP-fpm should reload. +Then, add the `php-fpm:reload` task at the end of your deployments by using the `after` method like so. +```php +set('php_fpm_version', '8.0'); +after('deploy', 'php-fpm:reload'); +``` Automatically detects by using [bin/php](/docs/recipe/common.md#bin/php). ```php title="Default value" diff --git a/docs/contrib/rabbit.md b/docs/contrib/rabbit.md index 1b1134dbc..da83225f1 100644 --- a/docs/contrib/rabbit.md +++ b/docs/contrib/rabbit.md @@ -12,6 +12,41 @@ require 'contrib/rabbit.php'; +### Installing +```php +deploy.php +require 'recipe/rabbit.php'; +``` +### Configuration options +- **rabbit** *(required)*: accepts an *array* with the connection information to [rabbitmq](http://www.rabbitmq.com) server token and team name. +You can provide also other configuration options: + - *host* - default is localhost + - *port* - default is 5672 + - *username* - default is *guest* + - *password* - default is *guest* + - *channel* - no default value, need to be specified via config + - *message* - default is **Deployment to '$host' on *$prod* was successful\n$releasePath** + - *vhost* - default is +```php +deploy.php +set('rabbit', [ + 'host' => 'localhost', + 'port' => '5672', + 'username' => 'guest', + 'password' => 'guest', + 'channel' => 'notify-channel', + 'vhost' => '/my-app' +]); +``` +### Suggested Usage +Since you should only notify RabbitMQ channel of a successful deployment, the `deploy:rabbit` task should be executed right at the end. +```php +deploy.php +before('deploy:end', 'deploy:rabbit'); +``` + + + ## Tasks ### deploy:rabbit diff --git a/docs/contrib/raygun.md b/docs/contrib/raygun.md index 251c42d63..20f571a3a 100644 --- a/docs/contrib/raygun.md +++ b/docs/contrib/raygun.md @@ -12,6 +12,22 @@ require 'contrib/raygun.php'; +## Configuration +- `raygun_api_key` – the API key of your Raygun application +- `raygun_version` – the version of your application that this deployment is releasing +- `raygun_owner_name` – the name of the person creating this deployment +- `raygun_email` – the email of the person creating this deployment +- `raygun_comment` – the deployment notes +- `raygun_scm_identifier` – the commit that this deployment was built off +- `raygun_scm_type` - the source control system you use +## Usage +To notify Raygun of a successful deployment, you can use the 'raygun:notify' task after a deployment. +```php +after('deploy', 'raygun:notify'); +``` + + + ## Tasks ### raygun:notify diff --git a/docs/contrib/rocketchat.md b/docs/contrib/rocketchat.md index 4a8092b94..a03b578dd 100644 --- a/docs/contrib/rocketchat.md +++ b/docs/contrib/rocketchat.md @@ -11,6 +11,49 @@ require 'contrib/rocketchat.php'; [Source](/contrib/rocketchat.php) + +## Installing +Create a RocketChat incoming webhook, through the administration panel. +Add hook on deploy: +``` +before('deploy', 'rocketchat:notify'); +``` +## Configuration + - `rocketchat_webhook` - incoming rocketchat webook **required** + ``` + set('rocketchat_webhook', 'https://rocketchat.yourcompany.com/hooks/XXXXX'); + ``` + - `rocketchat_title` - the title of the application, defaults to `{{application}}` + - `rocketchat_text` - notification message + ``` + set('rocketchat_text', '_{{user}}_ deploying {{branch}} to {{target}}'); + ``` + - `rocketchat_success_text` – success template, default: + ``` + set('rocketchat_success_text', 'Deploy to *{{target}}* successful'); + ``` + - `rocketchat_failure_text` – failure template, default: + ``` + set('rocketchat_failure_text', 'Deploy to *{{target}}* failed'); + ``` + - `rocketchat_color` – color's attachment + - `rocketchat_success_color` – success color's attachment + - `rocketchat_failure_color` – failure color's attachment +## Usage +If you want to notify only about beginning of deployment add this line only: +```php +before('deploy', 'rocketchat:notify'); +``` +If you want to notify about successful end of deployment add this too: +```php +after('deploy:success', 'rocketchat:notify:success'); +``` +If you want to notify about failed deployment add this too: +```php +after('deploy:failed', 'rocketchat:notify:failure'); +``` + + ## Configuration ### rockchat_title [Source](https://github.com/deployphp/deployer/blob/master/contrib/rocketchat.php#L65) diff --git a/docs/contrib/rollbar.md b/docs/contrib/rollbar.md index 289f1d71b..849d839b9 100644 --- a/docs/contrib/rollbar.md +++ b/docs/contrib/rollbar.md @@ -11,6 +11,21 @@ require 'contrib/rollbar.php'; [Source](/contrib/rollbar.php) + +## Configuration +- `rollbar_token` – access token to rollbar api +- `rollbar_comment` – comment about deploy, default to + ```php + set('rollbar_comment', '_{{user}}_ deploying `{{branch}}` to *{{target}}*'); + ``` +- `rollbar_username` – rollbar user name +## Usage +Since you should only notify Rollbar channel of a successful deployment, the `rollbar:notify` task should be executed right at the end. +```php +after('deploy', 'rollbar:notify'); +``` + + ## Configuration ### rollbar_comment [Source](https://github.com/deployphp/deployer/blob/master/contrib/rollbar.php#L27) diff --git a/docs/contrib/rsync.md b/docs/contrib/rsync.md index 936f2031a..94d5c9b72 100644 --- a/docs/contrib/rsync.md +++ b/docs/contrib/rsync.md @@ -11,6 +11,93 @@ require 'contrib/rsync.php'; [Source](/contrib/rsync.php) + +:::warning +This must not be confused with `/src/Utility/Rsync.php`, deployer's built-in rsync. Their configuration options are also very different, read carefully below. +::: +## Configuration options +- **rsync**: Accepts an array with following rsync options (all are optional and defaults are ok): + - *exclude*: accepts an *array* with patterns to be excluded from sending to server + - *exclude-file*: accepts a *string* containing absolute path to file, which contains exclude patterns + - *include*: accepts an *array* with patterns to be included in sending to server + - *include-file*: accepts a *string* containing absolute path to file, which contains include patterns + - *filter*: accepts an *array* of rsync filter rules + - *filter-file*: accepts a *string* containing merge-file filename. + - *filter-perdir*: accepts a *string* containing merge-file filename to be scanned and merger per each directory in rsync list on files to send + - *flags*: accepts a *string* of flags to set when calling rsync command. Please **avoid** flags that accept params, and use *options* instead. + - *options*: accepts an *array* of options to set when calling rsync command. **DO NOT** prefix options with `--` as it's automatically added. + - *timeout*: accepts an *int* defining timeout for rsync command to run locally. +### Sample Configuration: +Following is default configuration. By default rsync ignores only git dir and `deploy.php` file. +```php +deploy.php +set('rsync',[ + 'exclude' => [ + '.git', + 'deploy.php', + ], + 'exclude-file' => false, + 'include' => [], + 'include-file' => false, + 'filter' => [], + 'filter-file' => false, + 'filter-perdir'=> false, + 'flags' => 'rz', // Recursive, with compress + 'options' => ['delete'], + 'timeout' => 60, +]); +``` +If You have multiple excludes, You can put them in file and reference that instead. If You use `deploy:rsync_warmup` You could set additional options that could speed-up and/or affect way things are working. For example: +```php +deploy.php +set('rsync',[ + 'exclude' => ['excludes_file'], + 'exclude-file' => '/tmp/localdeploys/excludes_file', //Use absolute path to avoid possible rsync problems + 'include' => [], + 'include-file' => false, + 'filter' => [], + 'filter-file' => false, + 'filter-perdir' => false, + 'flags' => 'rzcE', // Recursive, with compress, check based on checksum rather than time/size, preserve Executable flag + 'options' => ['delete', 'delete-after', 'force'], //Delete after successful transfer, delete even if deleted dir is not empty + 'timeout' => 3600, //for those huge repos or crappy connection +]); +``` +### Parameter +- **rsync_src**: per-host rsync source. This can be server, stage or whatever-dependent. By default it's set to current directory +- **rsync_dest**: per-host rsync destination. This can be server, stage or whatever-dependent. by default it's equivalent to release deploy destination. +### Sample configurations: +This is default configuration: +```php +set('rsync_src', __DIR__); +set('rsync_dest','{{release_path}}'); +``` +If You use local deploy recipe You can set src to local release: +```php +host('hostname') + ->hostname('10.10.10.10') + ->port(22) + ->set('deploy_path','/your/remote/path/app') + ->set('rsync_src', '/your/local/path/app') + ->set('rsync_dest','{{release_path}}'); +``` +## Usage +- `rsync` task + Set `rsync_src` to locally cloned repository and rsync to `rsync_dest`. Then set this task instead of `deploy:update_code` in Your `deploy` task if Your hosting provider does not allow git. +- `rsync:warmup` task + If Your deploy task looks like: + ```php + task('deploy', [ + 'deploy:prepare', + 'deploy:release', + 'rsync', + 'deploy:vendors', + 'deploy:symlink', + ])->desc('Deploy your project'); + ``` + And Your `rsync_dest` is set to `{{release_path}}` then You could add this task to run before `rsync` task or after `deploy:release`, whatever is more convenient. + + ## Configuration ### rsync [Source](https://github.com/deployphp/deployer/blob/master/contrib/rsync.php#L120) diff --git a/docs/contrib/sentry.md b/docs/contrib/sentry.md index c9e5e50f8..434131fa3 100644 --- a/docs/contrib/sentry.md +++ b/docs/contrib/sentry.md @@ -12,3 +12,49 @@ require 'contrib/sentry.php'; +### Configuration options +- **organization** *(required)*: the slug of the organization the release belongs to. +- **projects** *(required)*: array of slugs of the projects to create a release for. +- **token** *(required)*: authentication token. Can be created at [https://sentry.io/settings/account/api/auth-tokens/] +- **version** *(required)* – a version identifier for this release. +Can be a version number, a commit hash etc. (Defaults is set to git log -n 1 --format="%h".) +- **version_prefix** *(optional)* - a string prefixed to version. +Releases are global per organization so indipentent projects needs to prefix version number with unique string to avoid conflicts +- **environment** *(optional)* - the environment you’re deploying to. By default framework's environment is used. +For example for symfony, *symfony_env* configuration is read otherwise defaults to 'prod'. +- **ref** *(optional)* – an optional commit reference. This is useful if a tagged version has been provided. +- **refs** *(optional)* - array to indicate the start and end commits for each repository included in a release. +Head commits must include parameters *repository* and *commit*) (the HEAD sha). +They can optionally include *previousCommit* (the sha of the HEAD of the previous release), +which should be specified if this is the first time you’ve sent commit data. +- **commits** *(optional)* - array commits data to be associated with the release. +Commits must include parameters *id* (the sha of the commit), and can optionally include *repository*, +*message*, *author_name*, *author_email* and *timestamp*. By default will send all new commits, +unless it's a first release, then only first 200 will be sent. +- **url** *(optional)* – a URL that points to the release. This can be the path to an online interface to the sourcecode for instance. +- **date_released** *(optional)* – date that indicates when the release went live. If not provided the current time is assumed. +- **sentry_server** *(optional)* – sentry server (if you host it yourself). defaults to hosted sentry service. +- **date_deploy_started** *(optional)* - date that indicates when the deploy started. Defaults to current time. +- **date_deploy_finished** *(optional)* - date that indicates when the deploy ended. If not provided, the current time is used. +- **deploy_name** *(optional)* - name of the deploy +- **git_version_command** *(optional)* - the command that retrieves the git version information (Defaults is set to git log -n 1 --format="%h", other options are git describe --tags --abbrev=0) +```php +deploy.php +set('sentry', [ + 'organization' => 'exampleorg', + 'projects' => [ + 'exampleproj' + ], + 'token' => 'd47828...', + 'version' => '0.0.1', +]); +``` +### Suggested Usage +Since you should only notify Sentry of a successful deployment, the deploy:sentry task should be executed right at the end. +```php +deploy.php +after('deploy', 'deploy:sentry'); +``` + + + diff --git a/docs/contrib/slack.md b/docs/contrib/slack.md index 4c8cb23c7..d8185c25d 100644 --- a/docs/contrib/slack.md +++ b/docs/contrib/slack.md @@ -11,6 +11,54 @@ require 'contrib/slack.php'; [Source](/contrib/slack.php) + +## Installing +Add to Slack +Add hook on deploy: +```php +before('deploy', 'slack:notify'); +``` +## Configuration +- `slack_webhook` – slack incoming webhook url, **required** + ``` + set('slack_webhook', 'https://hooks.slack.com/...'); + ``` +- `slack_channel` - channel to send notification to. The default is the channel configured in the webhook +- `slack_title` – the title of application, default `{{application}}` +- `slack_text` – notification message template, markdown supported + ``` + set('slack_text', '_{{user}}_ deploying `{{branch}}` to *{{target}}*'); + ``` +- `slack_success_text` – success template, default: + ``` + set('slack_success_text', 'Deploy to *{{target}}* successful'); + ``` +- `slack_failure_text` – failure template, default: + ``` + set('slack_failure_text', 'Deploy to *{{target}}* failed'); + ``` +- `slack_color` – color's attachment +- `slack_success_color` – success color's attachment +- `slack_failure_color` – failure color's attachment +- `slack_fields` - set attachments fields for pretty output in Slack, default: + ``` + set('slack_fields', []); + ``` +## Usage +If you want to notify only about beginning of deployment add this line only: +```php +before('deploy', 'slack:notify'); +``` +If you want to notify about successful end of deployment add this too: +```php +after('deploy:success', 'slack:notify:success'); +``` +If you want to notify about failed deployment add this too: +```php +after('deploy:failed', 'slack:notify:failure'); +``` + + ## Configuration ### slack_channel [Source](https://github.com/deployphp/deployer/blob/master/contrib/slack.php#L70) diff --git a/docs/contrib/supervisord-monitor.md b/docs/contrib/supervisord-monitor.md index bde576e73..42d7287da 100644 --- a/docs/contrib/supervisord-monitor.md +++ b/docs/contrib/supervisord-monitor.md @@ -12,6 +12,72 @@ require 'contrib/supervisord-monitor.php'; +### Description +This is a recipe that uses the [Supervisord server monitoring project](https://github.com/mlazarov/supervisord-monitor). +With this recipe the possibility is created to restart a supervisord process through the Supervisor Monitor webtool, by using cURL. This workaround is particular usefull when the deployment user has unsuficient rights to restart a daemon process from the cli. +### Configuration +``` +set('supervisord', [ + 'uri' => 'https://youruri.xyz/supervisor', + 'basic_auth_user' => 'username', + 'basic_auth_password' => 'password', + 'process_name' => 'process01', +]); +``` +or +``` +set('supervisord_uri', 'https://youruri.xyz/supervisor'); +set('supervisord_basic_auth_user', 'username'); +set('supervisord_basic_auth_password', 'password'); +set('supervisord_process_name', 'process01'); +``` +- `supervisord` – array with configuration for Supervisord + - `uri` – URI to the Supervisord monitor page + - `basic_auth_user` – Basic auth username to access the URI + - `basic_auth_password` – Basic auth password to access the URI + - `process_name` – the process name, as visible in the Supervisord monitor page. Multiple processes can be listed here, comma separated +### Task +- `supervisord-monitor:restart` Restarts given processes +- `supervisord-monitor:stop` Stops given processes +- `supervisord-monitor:start` Starts given processes +### Usage +A complete example with configs, staging and deployment +``` + 'https://youruri.xyz/supervisor', + 'basic_auth_user' => 'username', + 'basic_auth_password' => 'password', + 'process_name' => 'process01', +]); +host('staging.myproject.com') + ->set('branch', 'develop') + ->set('labels', ['stage' => 'staging']); +host('myproject.com') + ->set('branch', 'main') + ->set('labels', ['stage' => 'production']); +Tasks +task('build', function () { + run('cd {{release_path}} && build'); +}); +task('deploy', [ + 'build', + 'supervisord', +]); +task('supervisord', ['supervisord-monitor:restart']) + ->select('stage=production'); +``` + + + ## Tasks ### supervisord-monitor:restart diff --git a/docs/contrib/telegram.md b/docs/contrib/telegram.md index f3cf2b34a..d8ab57913 100644 --- a/docs/contrib/telegram.md +++ b/docs/contrib/telegram.md @@ -11,6 +11,50 @@ require 'contrib/telegram.php'; [Source](/contrib/telegram.php) + +## Installing + 1. Create telegram bot with [BotFather](https://t.me/BotFather) and grab the token provided + 2. Send `/start` to your bot and open https://api.telegram.org/bot{$TELEGRAM_TOKEN_HERE}/getUpdates + 3. Take chat_id from response +Add hook on deploy: +```php +before('deploy', 'telegram:notify'); +``` +## Configuration +- `telegram_token` – telegram bot token, **required** +- `telegram_chat_id` — chat ID to push messages to +- `telegram_proxy` - proxy connection string in [CURLOPT_PROXY](https://curl.haxx.se/libcurl/c/CURLOPT_PROXY.html) form like: + ``` + http://proxy:80 + socks5://user:password@host:3128 + ``` +- `telegram_title` – the title of application, default `{{application}}` +- `telegram_text` – notification message template + ``` + _{{user}}_ deploying `{{branch}}` to *{{target}}* + ``` +- `telegram_success_text` – success template, default: + ``` + Deploy to *{{target}}* successful + ``` +- `telegram_failure_text` – failure template, default: + ``` + Deploy to *{{target}}* failed + ``` +## Usage +If you want to notify only about beginning of deployment add this line only: +```php +before('deploy', 'telegram:notify'); +``` +If you want to notify about successful end of deployment add this too: +```php +after('deploy:success', 'telegram:notify:success'); +``` +If you want to notify about failed deployment add this too: +```php +after('deploy:failed', 'telegram:notify:failure'); + + ## Configuration ### telegram_title [Source](https://github.com/deployphp/deployer/blob/master/contrib/telegram.php#L65) diff --git a/docs/contrib/webpack_encore.md b/docs/contrib/webpack_encore.md index 8dec71d15..bb80e69cb 100644 --- a/docs/contrib/webpack_encore.md +++ b/docs/contrib/webpack_encore.md @@ -14,11 +14,33 @@ require 'contrib/webpack_encore.php'; * [npm](/docs/contrib/npm.md) * [yarn](/docs/contrib/yarn.md) + +## Configuration +- **webpack_encore/package_manager** *(optional)*: set yarn or npm. We try to find if yarn or npm is available and used. +## Usage +```php +For Yarn +after('deploy:update_code', 'yarn:install'); +For npm +after('deploy:update_code', 'npm:install'); +after('deploy:update_code', 'webpack_encore:build'); +``` + + ## Configuration ### webpack_encore/package_manager [Source](https://github.com/deployphp/deployer/blob/master/contrib/webpack_encore.php#L25) - +## Configuration +- **webpack_encore/package_manager** *(optional)*: set yarn or npm. We try to find if yarn or npm is available and used. +## Usage +```php +For Yarn +after('deploy:update_code', 'yarn:install'); +For npm +after('deploy:update_code', 'npm:install'); +after('deploy:update_code', 'webpack_encore:build'); +``` :::info Autogenerated The value of this configuration is autogenerated on access. ::: diff --git a/docs/contrib/workplace.md b/docs/contrib/workplace.md index 161721cf4..e3798dbd8 100644 --- a/docs/contrib/workplace.md +++ b/docs/contrib/workplace.md @@ -11,6 +11,53 @@ require 'contrib/workplace.php'; [Source](/contrib/workplace.php) + +This recipes works with Custom Integrations and Publishing Bots. +Add hook on deploy: +``` +before('deploy', 'workplace:notify'); +``` +## Configuration + - `workplace_webhook` - incoming workplace webhook **required** + ``` + // With custom integration + set('workplace_webhook', 'https://graph.facebook.com//feed?access_token='); + // With publishing bot + set('workplace_webhook', 'https://graph.facebook.com/v3.0/group/feed?access_token='); + // Use markdown on message + set('workplace_webhook', 'https://graph.facebook.com//feed?access_token=&formatting=MARKDOWN'); + ``` + - `workplace_text` - notification message + ``` + set('workplace_text', '_{{user}}_ deploying `{{branch}}` to *{{target}}*'); + ``` + - `workplace_success_text` – success template, default: + ``` + set('workplace_success_text', 'Deploy to *{{target}}* successful'); + ``` + - `workplace_failure_text` – failure template, default: + ``` + set('workplace_failure_text', 'Deploy to *{{target}}* failed'); + ``` + - `workplace_edit_post` – whether to create a new post for deploy result, or edit the first one created, default creates a new post: + ``` + set('workplace_edit_post', false); + ``` +## Usage +If you want to notify only about beginning of deployment add this line only: +```php +before('deploy', 'workplace:notify'); +``` +If you want to notify about successful end of deployment add this too: +```php +after('deploy:success', 'workplace:notify:success'); +``` +If you want to notify about failed deployment add this too: +```php +after('deploy:failed', 'workplace:notify:failure'); +``` + + ## Configuration ### workplace_text [Source](https://github.com/deployphp/deployer/blob/master/contrib/workplace.php#L71) diff --git a/docs/contrib/yammer.md b/docs/contrib/yammer.md index 58256f983..cd732fd7f 100644 --- a/docs/contrib/yammer.md +++ b/docs/contrib/yammer.md @@ -11,6 +11,43 @@ require 'contrib/yammer.php'; [Source](/contrib/yammer.php) + +Add hook on deploy: +```php +before('deploy', 'yammer:notify'); +``` +## Configuration +- `yammer_url` – The URL to the message endpoint, default is https://www.yammer.com/api/v1/messages.json +- `yammer_token` *(required)* – Yammer auth token +- `yammer_group_id` *(required)* - Group ID +- `yammer_title` – the title of application, default `{{application}}` +- `yammer_body` – notification message template, default: + ``` + {{user}} deploying {{branch}} to {{target}} + ``` +- `yammer_success_body` – success template, default: + ``` + Deploy to {{target}} successful + ``` +- `yammer_failure_body` – failure template, default: + ``` + Deploy to {{target}} failed + ``` +## Usage +If you want to notify only about beginning of deployment add this line only: +```php +before('deploy', 'yammer:notify'); +``` +If you want to notify about successful end of deployment add this too: +```php +after('deploy:success', 'yammer:notify:success'); +``` +If you want to notify about failed deployment add this too: +```php +after('deploy:failed', 'yammer:notify:failure'); +``` + + ## Configuration ### yammer_url [Source](https://github.com/deployphp/deployer/blob/master/contrib/yammer.php#L55) diff --git a/docs/contrib/yarn.md b/docs/contrib/yarn.md index 7cf2e88fe..5a188b3b5 100644 --- a/docs/contrib/yarn.md +++ b/docs/contrib/yarn.md @@ -11,11 +11,25 @@ require 'contrib/yarn.php'; [Source](/contrib/yarn.php) + +## Configuration +- **bin/yarn** *(optional)*: set Yarn binary, automatically detected otherwise. +## Usage +```php +after('deploy:update_code', 'yarn:install'); +``` + + ## Configuration ### bin/yarn [Source](https://github.com/deployphp/deployer/blob/master/contrib/yarn.php#L16) - +## Configuration +- **bin/yarn** *(optional)*: set Yarn binary, automatically detected otherwise. +## Usage +```php +after('deploy:update_code', 'yarn:install'); +``` ```php title="Default value" return which('yarn'); diff --git a/docs/recipe/cakephp.md b/docs/recipe/cakephp.md index 00a51a883..dd627ddbd 100644 --- a/docs/recipe/cakephp.md +++ b/docs/recipe/cakephp.md @@ -43,7 +43,7 @@ The [deploy](#deploy) task of **Cakephp** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The cakephp recipe is based on the [common](/docs/recipe/common.md) recipe. @@ -54,6 +54,7 @@ The cakephp recipe is based on the [common](/docs/recipe/common.md) recipe. Overrides [shared_dirs](/docs/recipe/deploy/shared.md#shared_dirs) from `recipe/deploy/shared.php`. +CakePHP 4 Project Template configuration CakePHP 4 Project Template shared dirs ```php title="Default value" diff --git a/docs/recipe/codeigniter.md b/docs/recipe/codeigniter.md index 8c80aa9ea..674a06cba 100644 --- a/docs/recipe/codeigniter.md +++ b/docs/recipe/codeigniter.md @@ -41,7 +41,7 @@ The [deploy](#deploy) task of **Codeigniter** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The codeigniter recipe is based on the [common](/docs/recipe/common.md) recipe. diff --git a/docs/recipe/codeigniter4.md b/docs/recipe/codeigniter4.md index f8362d474..cbbc04755 100644 --- a/docs/recipe/codeigniter4.md +++ b/docs/recipe/codeigniter4.md @@ -43,7 +43,7 @@ The [deploy](#deploy) task of **Codeigniter 4** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The codeigniter4 recipe is based on the [common](/docs/recipe/common.md) recipe. @@ -133,7 +133,7 @@ return $matches[0][0] ?? 5.5; Shows file cache information in the current system. - +Discover & Checks ### spark:config:check @@ -197,7 +197,7 @@ Displays all routes. Generates a new encryption key and writes it in an `.env` file. - +Actions ### spark:optimize @@ -221,7 +221,7 @@ Discovers and executes all predefined Publisher classes. Create a new database schema. - +Database and migrations. ### spark:db:seed @@ -277,7 +277,7 @@ Displays a list of all migrations and whether they\'ve been run or not. Clears the current system caches. - +Housekeeping ### spark:debugbar:clear diff --git a/docs/recipe/common.md b/docs/recipe/common.md index 6bffb9170..08abd5398 100644 --- a/docs/recipe/common.md +++ b/docs/recipe/common.md @@ -241,7 +241,7 @@ This task is group task which contains next tasks: ### deploy:success [Source](https://github.com/deployphp/deployer/blob/master/recipe/common.php#L166) - +Deploys your project. Prints success message diff --git a/docs/recipe/contao.md b/docs/recipe/contao.md index 224aa8d21..2ede64ba9 100644 --- a/docs/recipe/contao.md +++ b/docs/recipe/contao.md @@ -44,7 +44,7 @@ The [deploy](#deploy) task of **Contao** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The contao recipe is based on the [symfony](/docs/recipe/symfony.md) recipe. diff --git a/docs/recipe/craftcms.md b/docs/recipe/craftcms.md index 5142b9dfe..cef400512 100644 --- a/docs/recipe/craftcms.md +++ b/docs/recipe/craftcms.md @@ -104,7 +104,7 @@ Overrides [writable_dirs](/docs/recipe/deploy/writable.md#writable_dirs) from `r Runs garbage collection. - +Garbage collection ### deploy @@ -112,7 +112,7 @@ Runs garbage collection. Deploys Craft CMS. - +Main deploy This task is group task which contains next tasks: diff --git a/docs/recipe/deploy/writable.md b/docs/recipe/deploy/writable.md index 3bcca951c..adc841206 100644 --- a/docs/recipe/deploy/writable.md +++ b/docs/recipe/deploy/writable.md @@ -15,7 +15,9 @@ require 'recipe/deploy/writable.php'; ### http_user [Source](https://github.com/deployphp/deployer/blob/master/recipe/deploy/writable.php#L9) - +Used to make a writable directory by a server. +Used in `chown` and `acl` modes of [writable_mode](/docs/recipe/deploy/writable.md#writable_mode). +Attempts automatically to detect http user in process list. :::info Autogenerated The value of this configuration is autogenerated on access. ::: diff --git a/docs/recipe/drupal7.md b/docs/recipe/drupal7.md index fd29c3398..2819ec6eb 100644 --- a/docs/recipe/drupal7.md +++ b/docs/recipe/drupal7.md @@ -40,7 +40,7 @@ The [deploy](#deploy) task of **Drupal 7** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The drupal7 recipe is based on the [common](/docs/recipe/common.md) recipe. diff --git a/docs/recipe/drupal8.md b/docs/recipe/drupal8.md index 1b8b570a2..5e2ad6b06 100644 --- a/docs/recipe/drupal8.md +++ b/docs/recipe/drupal8.md @@ -40,7 +40,7 @@ The [deploy](#deploy) task of **Drupal 8** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The drupal8 recipe is based on the [common](/docs/recipe/common.md) recipe. diff --git a/docs/recipe/flow_framework.md b/docs/recipe/flow_framework.md index 86bbbf5c5..6f3edf6b5 100644 --- a/docs/recipe/flow_framework.md +++ b/docs/recipe/flow_framework.md @@ -43,7 +43,7 @@ The [deploy](#deploy) task of **Flow Framework** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The flow_framework recipe is based on the [common](/docs/recipe/common.md) recipe. diff --git a/docs/recipe/fuelphp.md b/docs/recipe/fuelphp.md index f294e5c99..9c51d4c53 100644 --- a/docs/recipe/fuelphp.md +++ b/docs/recipe/fuelphp.md @@ -41,7 +41,7 @@ The [deploy](#deploy) task of **Fuelphp** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The fuelphp recipe is based on the [common](/docs/recipe/common.md) recipe. diff --git a/docs/recipe/joomla.md b/docs/recipe/joomla.md index 759d7a5a3..d5fb99e9f 100644 --- a/docs/recipe/joomla.md +++ b/docs/recipe/joomla.md @@ -40,7 +40,7 @@ The [deploy](#deploy) task of **Joomla** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The joomla recipe is based on the [common](/docs/recipe/common.md) recipe. diff --git a/docs/recipe/laravel.md b/docs/recipe/laravel.md index 7cd189b92..986e57da8 100644 --- a/docs/recipe/laravel.md +++ b/docs/recipe/laravel.md @@ -47,7 +47,7 @@ The [deploy](#deploy) task of **Laravel** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The laravel recipe is based on the [common](/docs/recipe/common.md) recipe. @@ -142,7 +142,7 @@ Overrides [public_path](/docs/recipe/provision/website.md#public_path) from `rec Puts the application into maintenance / demo mode. - +Maintenance mode. ### artisan:up @@ -158,7 +158,7 @@ Brings the application out of maintenance mode. Sets the application key. - +Generate keys. ### artisan:passport:keys @@ -174,7 +174,7 @@ Creates the encryption keys for API authentication. Seeds the database with records. - +Database and migrations. ### artisan:migrate @@ -214,7 +214,7 @@ Shows the status of each migration. Flushes the application cache. - +Cache and optimizations. ### artisan:config:cache @@ -326,7 +326,7 @@ Clears all compiled view files. Lists all of the failed queue jobs. - +Queue and Horizon. ### artisan:queue:flush @@ -422,7 +422,7 @@ Publish all of the Horizon resources. Clears all entries from Telescope. - +Telescope. ### artisan:​telescope:prune @@ -438,7 +438,7 @@ Prunes stale entries from the Telescope database. Starts the octane server. - +Octane. ### artisan:octane:reload @@ -470,7 +470,7 @@ Check the status of the octane server. Publish all of the Laravel Nova resources. - +Nova. ### artisan:reverb:start @@ -478,7 +478,7 @@ Publish all of the Laravel Nova resources. Starts the Reverb server. - +Reverb. ### artisan:reverb:restart @@ -494,7 +494,7 @@ Restarts the Reverb server. Starts the Pulse server. - +Pulse. ### artisan:pulse:restart diff --git a/docs/recipe/magento.md b/docs/recipe/magento.md index 6fed6fc36..89fe5177d 100644 --- a/docs/recipe/magento.md +++ b/docs/recipe/magento.md @@ -41,7 +41,7 @@ The [deploy](#deploy) task of **Magento** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The magento recipe is based on the [common](/docs/recipe/common.md) recipe. @@ -52,6 +52,7 @@ The magento recipe is based on the [common](/docs/recipe/common.md) recipe. Overrides [shared_dirs](/docs/recipe/deploy/shared.md#shared_dirs) from `recipe/deploy/shared.php`. +Magento Configuration Magento shared dirs ```php title="Default value" diff --git a/docs/recipe/magento2.md b/docs/recipe/magento2.md index 8fa29473c..17cf9b238 100644 --- a/docs/recipe/magento2.md +++ b/docs/recipe/magento2.md @@ -50,7 +50,7 @@ The [deploy](#deploy) task of **Magento 2** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project In addition the **Magento 2** recipe contains an artifact deployment. @@ -108,7 +108,7 @@ The [artifact:build](#artifact:build) command of **Magento 2** consists of: * [b * [cachetool:clear:opcache](/docs/contrib/cachetool.md#cachetoolclearopcache) – Clears OPcode cache * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The magento2 recipe is based on the [common](/docs/recipe/common.md) recipe. @@ -117,6 +117,7 @@ The magento2 recipe is based on the [common](/docs/recipe/common.md) recipe. ### static_content_locales [Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L27) +Configuration By default setup:static-content:deploy uses `en_US`. To change that, simply put `set('static_content_locales', 'en_US de_DE');` in you deployer script. @@ -129,6 +130,7 @@ in you deployer script. ### magento_themes [Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L44) +Configuration You can also set the themes to run against. By default it'll deploy all themes - `add('magento_themes', ['Magento/luma', 'Magento/backend']);` If the themes are set as a simple list of strings, then all languages defined in [static_content_locales](/docs/recipe/magento2.md#static_content_locales) are @@ -191,6 +193,7 @@ This setting supports the same options/structure as [magento_themes](/docs/recip ### static_content_jobs [Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L65) +Configuration Also set the number of concurrent jobs to run. The default is 1 Update using: `set('static_content_jobs', '1');` @@ -355,6 +358,7 @@ true ### artifact_file [Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L347) +Artifact deployment section The file the artifact is saved to ```php title="Default value" @@ -451,6 +455,7 @@ Array of shared directories that will be added to the default shared_dirs withou Compiles magento di. +Tasks To work correctly with artifact deployment, it is necessary to set the MAGE_MODE correctly in `app/etc/config.php` e.g. ```php @@ -607,7 +612,7 @@ This task is group task which contains next tasks: Packages all relevant files in an artifact. - +tasks section ### artifact:upload diff --git a/docs/recipe/pimcore.md b/docs/recipe/pimcore.md index 332d00303..3a678bd7f 100644 --- a/docs/recipe/pimcore.md +++ b/docs/recipe/pimcore.md @@ -42,7 +42,7 @@ The [deploy](#deploy) task of **Pimcore** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The pimcore recipe is based on the [symfony](/docs/recipe/symfony.md) recipe. diff --git a/docs/recipe/prestashop.md b/docs/recipe/prestashop.md index 0036850f1..4caf2f02c 100644 --- a/docs/recipe/prestashop.md +++ b/docs/recipe/prestashop.md @@ -40,7 +40,7 @@ The [deploy](#deploy) task of **Prestashop** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The prestashop recipe is based on the [common](/docs/recipe/common.md) recipe. diff --git a/docs/recipe/shopware.md b/docs/recipe/shopware.md index 84dfa39f2..4404dc748 100644 --- a/docs/recipe/shopware.md +++ b/docs/recipe/shopware.md @@ -51,11 +51,38 @@ The [deploy](#deploy) task of **Shopware** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The shopware recipe is based on the [common](/docs/recipe/common.md) recipe. + +## Usage + +Add `repository` to your _deploy.php_ file: + +```php +set('repository', 'git@github.com:shopware/production.git'); +``` + +configure host: +```php +host('SSH-HOSTNAME') + ->set('remote_user', 'SSH-USER') + ->set('deploy_path', '/var/www/shopware') // This is the path, where deployer will create its directory structure + ->set('http_user', 'www-data') // Not needed, if the `user` is the same user, the webserver is running with + ->set('http_group', 'www-data') + ->set('writable_mode', 'chmod') + ->set('writable_recursive', true) + ->set('become', 'www-data'); // You might want to change user to execute remote tasks because of access rights of created cache files +``` + +:::note +Please remember that the installation must be modified so that it can be +[build without database](https://developer.shopware.com/docs/guides/hosting/installation-updates/deployments/build-w-o-db#compiling-the-storefront-without-database). +::: + + ## Configuration ### bin/console [Source](https://github.com/deployphp/deployer/blob/master/recipe/shopware.php#L35) diff --git a/docs/recipe/silverstripe.md b/docs/recipe/silverstripe.md index 8f901805d..488b1efde 100644 --- a/docs/recipe/silverstripe.md +++ b/docs/recipe/silverstripe.md @@ -42,7 +42,7 @@ The [deploy](#deploy) task of **Silverstripe** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The silverstripe recipe is based on the [common](/docs/recipe/common.md) recipe. @@ -51,7 +51,7 @@ The silverstripe recipe is based on the [common](/docs/recipe/common.md) recipe. ### shared_assets [Source](https://github.com/deployphp/deployer/blob/master/recipe/silverstripe.php#L13) - +Silverstripe configuration ```php title="Default value" if (test('[ -d {{release_or_current_path}}/public ]') || test('[ -d {{deploy_path}}/shared/public ]')) { diff --git a/docs/recipe/spiral.md b/docs/recipe/spiral.md index 9a49876dc..c09ea0c79 100644 --- a/docs/recipe/spiral.md +++ b/docs/recipe/spiral.md @@ -45,7 +45,7 @@ The [deploy](#deploy) task of **Spiral** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project * [deploy:restart-rr](/docs/recipe/spiral.md#deployrestart-rr) – Restart RoadRunner diff --git a/docs/recipe/statamic.md b/docs/recipe/statamic.md index 7057b4e42..e8c917fd3 100644 --- a/docs/recipe/statamic.md +++ b/docs/recipe/statamic.md @@ -45,7 +45,7 @@ The [deploy](#deploy) task of **Statamic** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The statamic recipe is based on the [laravel](/docs/recipe/laravel.md) recipe. @@ -71,7 +71,7 @@ return $matches[0][0] ?? 'unknown'; Rebuilds the cached addon package manifest. - +Addons ### statamic:assets:generate-presets @@ -79,7 +79,7 @@ Rebuilds the cached addon package manifest. Generates asset preset manipulations. - +Assets ### statamic:assets:meta @@ -95,7 +95,7 @@ Generates asset metadata files. Git add and commit tracked content. - +Git ### statamic:glide:clear @@ -103,7 +103,7 @@ Git add and commit tracked content. Clears the Glide image cache. - +Glide ### statamic:responsive:generate @@ -111,7 +111,7 @@ Clears the Glide image cache. Generates responsive images. - +Responsive Images (not in the core) ### statamic:responsive:regenerate @@ -127,7 +127,7 @@ Regenerate responsive images. Inserts an item into its search indexes. - +Search ### statamic:search:update @@ -143,7 +143,7 @@ Update a search index. Clears the "Stache" cache. - +Stache ### statamic:stache:doctor @@ -175,7 +175,7 @@ Builds the "Stache" cache. Clears the static page cache. - +Static ### statamic:static:warm @@ -191,7 +191,7 @@ Warms the static cache by visiting all URLs. Outputs details helpful for support requests. - +Support ### statamic:updates:run @@ -199,7 +199,7 @@ Outputs details helpful for support requests. Runs update scripts from specific version. - +Updated ### deploy @@ -207,7 +207,8 @@ Runs update scripts from specific version. Deploys your project. - +Main Deploy Script for Statamic, which +will overwrite the Laravel default. This task is group task which contains next tasks: diff --git a/docs/recipe/sulu.md b/docs/recipe/sulu.md index 4a0c5a9d1..5c7034d71 100644 --- a/docs/recipe/sulu.md +++ b/docs/recipe/sulu.md @@ -42,7 +42,7 @@ The [deploy](#deploy) task of **Sulu** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The sulu recipe is based on the [symfony](/docs/recipe/symfony.md) recipe. diff --git a/docs/recipe/symfony.md b/docs/recipe/symfony.md index 3dbac7a64..e1afa2810 100644 --- a/docs/recipe/symfony.md +++ b/docs/recipe/symfony.md @@ -42,7 +42,7 @@ The [deploy](#deploy) task of **Symfony** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The symfony recipe is based on the [common](/docs/recipe/common.md) recipe. diff --git a/docs/recipe/typo3.md b/docs/recipe/typo3.md index 196f4e871..86f479c02 100644 --- a/docs/recipe/typo3.md +++ b/docs/recipe/typo3.md @@ -41,7 +41,7 @@ The [deploy](#deploy) task of **TYPO3** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The typo3 recipe is based on the [common](/docs/recipe/common.md) recipe. diff --git a/docs/recipe/wordpress.md b/docs/recipe/wordpress.md index bcd796183..d89bf5d8a 100644 --- a/docs/recipe/wordpress.md +++ b/docs/recipe/wordpress.md @@ -40,7 +40,7 @@ The [deploy](#deploy) task of **WordPress** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The wordpress recipe is based on the [common](/docs/recipe/common.md) recipe. diff --git a/docs/recipe/yii.md b/docs/recipe/yii.md index 3d909e6d7..564f75ee8 100644 --- a/docs/recipe/yii.md +++ b/docs/recipe/yii.md @@ -42,7 +42,7 @@ The [deploy](#deploy) task of **Yii2** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The yii recipe is based on the [common](/docs/recipe/common.md) recipe. diff --git a/docs/recipe/zend_framework.md b/docs/recipe/zend_framework.md index e5f569506..26924fb66 100644 --- a/docs/recipe/zend_framework.md +++ b/docs/recipe/zend_framework.md @@ -41,7 +41,7 @@ The [deploy](#deploy) task of **Zend Framework** consists of: * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases - * [deploy:success](/docs/recipe/common.md#deploysuccess) – + * [deploy:success](/docs/recipe/common.md#deploysuccess) – Deploys your project The zend_framework recipe is based on the [common](/docs/recipe/common.md) recipe. diff --git a/src/Documentation/DocRecipe.php b/src/Documentation/DocRecipe.php index a568cbc51..5f24bb6cc 100644 --- a/src/Documentation/DocRecipe.php +++ b/src/Documentation/DocRecipe.php @@ -59,6 +59,11 @@ public function parse(string $content) for ($i = 0; $i < count($lines); $i++) { $line = $lines[$i]; + + if (empty($line)) { + continue; // Skip empty lines + } + $m = []; $match = function ($regexp) use ($line, &$m) { return preg_match("#$regexp#", $line, $m);