Add docgen

bin/docgen

@@ -9,6 +9,7 @@
 namespace Deployer;
 
 use Deployer\Documentation\ApiGen;
+use Deployer\Documentation\DocGen;
 use Deployer\Support\Changelog\Parser;
 use Symfony\Component\Console\Application;
 use Symfony\Component\Console\Input\ArgvInput;
@@ -22,16 +23,36 @@ chdir(realpath(__DIR__ . '/..'));
 $input = new ArgvInput();
 $output = new ConsoleOutput();
 $app = new Application('DocGen', '1.0.0');
+$app->setDefaultCommand('all');
 $io = new SymfonyStyle($input, $output);
 
-$app->setDefaultCommand('api');
-
-$app->register('api')->setCode(function () use ($io) {
+$api = function () use ($io) {
     $parser = new ApiGen();
     $parser->parse(file_get_contents(__DIR__ . '/../src/functions.php'));
     $md = $parser->markdown();
     file_put_contents(__DIR__ . '/../docs/api.md', $md);
-    $io->block('API Reference documentation is updated.');
-});
+    $io->block('API Reference documentation updated.');
+};
+
+$recipes = function () use ($input, $io) {
+    $docgen = new DocGen(__DIR__ . '/..');
+    $docgen->parse(__DIR__ . '/../recipe');
+    $docgen->parse(__DIR__ . '/../contrib');
+
+    if ($input->getOption('json')) {
+        echo json_encode($docgen->recipes, JSON_PRETTY_PRINT);
+        return;
+    }
+
+    $docgen->gen(__DIR__ . '/../docs');
+    $io->block('Recipes documentation updated.');
+};
+
+$app->register('api')->setCode($api);
+$app->register('recipes')->setCode($recipes)->addOption('json');
+$app->register('all')->setCode(function () use ($recipes, $api) {
+    $api();
+    $recipes();
+})->addOption('json');
 
 $app->run($input, $output);

contrib/bugsnag.php

@@ -1,9 +1,25 @@
 <?php
-/* (c) Tim Robertson <funkjedi@gmail.com>
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
+/*
+Add to your _deploy.php_
+
+```php
+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');
+```
+*/
 
 namespace Deployer;
 

contrib/cachetool.php

@@ -1,8 +1,48 @@
 <?php
-/* (c) Samuel Gordalina <samuel.gordalina@gmail.com>
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
+/*
+Add to your _deploy.php_
+
+```php
+require 'contrib/cachetool.php';
+```
+
+## Configuration
+
+- **cachetool** *(optional)*: accepts a *string* with the unix socket or ip address to php5-fpm. If `cachetool` is not given, then the application will look for a `cachetool.yml` file and read the configuration from there.
+
+    ```php
+    set('cachetool', '/var/run/php5-fpm.sock');
+    // or
+    set('cachetool', '127.0.0.1:9000');
+    ```
+
+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/php5-fpm.sock');
+```
+
+By default, if no `cachetool` parameter is provided, this recipe will fallback to the global setting.
+
+## Usage
+
+Since APC/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:apc');
+// or
+after('deploy:symlink', 'cachetool:clear:apcu');
+```
+
+## Read more
+
+Read more information about cachetool on the website:
+http://gordalina.github.io/cachetool/
  */
 
 namespace Deployer;

contrib/cimonitor.php

@@ -1,10 +1,67 @@
 <?php
-/* (c) Anton Medvedev <anton@medv.io>
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
+/*
+# CIMonitor recipe
+
+Monitor your deployments on [CIMonitor](https://github.com/CIMonitor/CIMonitor).
+
+![CIMonitorGif](https://www.steefmin.xyz/deployer-example.gif)
+
+Require cimonitor recipe in your `deploy.php` file:
+
+```php
+require 'contrib/cimonitor.php';
+```
 
+Add tasks on deploy:
+
+```php
+before('deploy', 'cimonitor:notify');
+after('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('success', 'cimonitor:notify:success');
+```
+
+If you want to notify about failed deployment add this too:
+
+```php
+after('deploy:failed', 'cimonitor:notify:failure');
+```
+ */
 namespace Deployer;
 
 use Deployer\Utility\Httpie;

contrib/cloudflare.php

@@ -1,10 +1,27 @@
 <?php
-/* (c) David Jordan / CyberDuck <david@cyber-duck.co.uk>
- * 
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
+/*
+### Installing
 
+Add to your _deploy.php_
+
+```php
+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.
+    - `domain` – The domain you want to clear
+
+### 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
+
+*/
 namespace Deployer;
 
 desc('Clearing Cloudflare Cache');

contrib/cpanel.php

@@ -1,5 +1,146 @@
 <?php
+/*
+### Installing
 
+Add to your _deploy.php_
+
+```php
+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
+
+```
+<?php
+
+namespace Deployer;
+use Dotenv\Dotenv;
+
+require 'vendor/autoload.php';
+(Dotenv::create(__DIR__))->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');
+```
+ */
 namespace Deployer;
 
 use Deployer\Task\Context;

contrib/crontab.php

@@ -1,8 +1,7 @@
 <?php
-/* (c) Asafov Sergey <asafov@newleaf.ru>
+/*
  * Recipe for crontab jobs deploy
- * Configuration:
-    You need no specify only crontab:jobs, which must be array of strings
+ * Configuration: You need no specify only crontab:jobs, which must be array of strings
  */
 namespace Deployer;