capistrano-magento2 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7c26fa9d5aee2efa6058343f4778e782cf3bd819
-  data.tar.gz: 9b0df9b6a112a8d1426bb6d952d5e88bde7720b0
+  metadata.gz: 56be092a97722587efac46aebf7fe0c433f4681b
+  data.tar.gz: f486eee26dd968fe28b18ea5b64b9e064096f1c6
 SHA512:
-  metadata.gz: 3fbce42ba76649f409114fabe570d5c5403feb556e031d08a7d002c76f2d21e1e47a2b74e4d00f51b7d479312e67ca5d9aeabde739d5a1b8c6c0bc43b40821c6
-  data.tar.gz: ae50da8be58fc6e35c8b11a0b62615897c13bc2d6cd9af178da4ceffaaece366e076b06895f3d61f8dc38f9a93c65aa68a96be177c5262b88bb338cf82e82c3d
+  metadata.gz: a6b0af5bb4454fe107d68bbf910d5bce2ca8af0b346f00a273bd615a331cefdeccc34624da09c11f3f61c4bed958300b7d825de2291df944566ffba4c7741a7f
+  data.tar.gz: 4e14ee33a8b6f3569ba0eaa7bd24a3af5c6dcbe7d3818d7890c0ce9b7a80aadcaf0dd30763aa77425e9365fba6c6cdc0c1dd64f980bd483e61f8c0ac7df75f5b

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Capistrano::Magento2 Change Log
 
+==========
+0.2.1
+
+* Fixed issue with initial deploy failing before 'current' link has been created on target
+
 0.2.0
 ==========
 

data/README.md

@@ -6,76 +6,158 @@ A Capistrano extension for Magento 2 deployments. Takes care of specific Magento
 
 ## Installation
 
-Add this line to your application's Gemfile:
+### Standalone Installation
 
-```ruby
-gem 'capistrano-magento2'
-```
+    $ gem install capistrano-magento2
 
-And then execute:
+### Using Bundler
 
-    $ bundle
+1. Add the following to your project's `Gemfile`:
 
-Or install it yourself as:
+    ```ruby
+    source 'https://rubygems.org'
+    gem 'capistrano-magento2'
+    ```
 
-    $ gem install capistrano-magento2
+2. Execute the following:
+
+        $ bundle install
 
 ## Usage
 
-Install Capistrano in your Magento project:
+1. Install Capistrano in your Magento project:
+    
+    ```shell
+    $ cd <project_root>
+    $ mkdir -p tools/cap
+    $ cd ./tools/cap
+    $ cap install
+    ```
+_Note: By default, Capistrano creates "staging" and "production" stages. If you want to define custom staging areas, you can do so using the "STAGES" option (e.g. `cap install STAGES=stage,prod`). Built-in notifications ([see below](#terminal-notifier-on-os-x)) confirm deploy action on both "production" and "prod" area names by default._
+
+2. Update your project's `Capfile` to look like the following:
+
+    ```ruby
+    # Load DSL and set up stages
+    require 'capistrano/setup'
+    
+    # Load Magento deployment tasks
+    require 'capistrano/magento2/deploy'
+    
+    # Load custom tasks from `lib/capistrano/tasks` if you have any defined
+    Dir.glob('lib/capistrano/tasks/*.rake').each { |r| import r }
+    ```
 
-```shell
-$ cd <project_root>
-$ mkdir -p tools/cap
-$ cd ./tools/cap
-$ cap install
-```
+3. Configure Capistrano, per the [Capistrano Configuration](#capistrano-configuration) section below.
 
-Update your project `Capfile` to look like the following:
+4. Configure your server(s), per the [Server Configuration](#server-configuration) section below.
 
-```ruby
-# Load DSL and set up stages
-require 'capistrano/setup'
+5. Deploy Magento 2 to staging or production by running the following command in the `tools/cap` directory:
+    
+    ```shell
+    $ cap staging deploy
+    ```
+    or
+    ```shell
+    $ cap production deploy
+    ```
+    
+## Default Configuration
 
-# Load Magento deployment tasks
-require 'capistrano/magento2/deploy'
-```
+### Capistrano Configuration
 
-## Default Configuration
+Before you can use Capistrano to deploy, you must configure the `config/deploy.rb` and `config/deploy/*.rb` files. This section will cover the basic details for configuring these files. Refer to the [Capistrano documentation](http://capistranorb.com/documentation/getting-started/preparing-your-application/#configure-your-server-addresses-in-the-generated-files) and [README](https://github.com/capistrano/capistrano/blob/master/README.md) for more details.
+
+1. Configuring `config/deploy.rb`
+    
+    Update the `:application` and `:repo_url` values in `config/deploy.rb`:
+    
+    ```ruby
+    # Something unique such as the website or company name
+    set :application, 'example'
+    # The repository that hosts the Magento 2 application (Magento should live in the root of the repo)
+    set :repo_url, 'git@github.com:acme/example-com.git'
+    ```
+
+2. Configuring `config/deploy/*.rb` files
+    
+    Capistrano allows you to use server-based or role-based syntax. You can read through the comments in the file to learn more about each option. If you have a single application server then the server-based syntax is the simplest configuration option.
+    
+    * Single application server
+        
+        If your stage and production environments consist of a single application server, your configuration files should look something like this:
+        
+        `config/deploy/production.rb`
+        ```ruby
+        server 'www.example.com', user: 'www-data', roles: %w{app db web}
+        
+        set :deploy_to, '/var/www/html'
+        set :branch, proc { `git rev-parse --abbrev-ref master`.chomp }
+        ```
+        
+        `config/deploy/staging.rb`
+        ```ruby
+        server 'stage.example.com', user: 'www-data', roles: %w{app db web}
+        
+        set :deploy_to, '/var/www/html'
+        set :branch, proc { `git rev-parse --abbrev-ref develop`.chomp }
+        ```
+        
+    * Multiple application servers
+        
+        Refer to the "role-based syntax" comments in the `config/deploy/*.rb` files or to the [Capistrano documentation](http://capistranorb.com/documentation/getting-started/preparing-your-application/#configure-your-server-addresses-in-the-generated-files) for details on how to configure multiple application servers.
 
 ### Capistrano Built-Ins
 
 For the sake of simplicity in new project setups `:linked_dirs` and `:linked_files` are pre-configured per the following.
 
 ```ruby
-    set :linked_files, [
-      'app/etc/env.php',
-      'var/.setup_cronjob_status',
-      'var/.update_cronjob_status',
-      'sitemap.xml'
-    ]
-    
-    set :linked_dirs, [
-      'pub/media', 
-      'var/backups', 
-      'var/composer_home', 
-      'var/importexport', 
-      'var/import_history', 
-      'var/log',
-      'var/session', 
-      'var/tmp'
-    ]
+set :linked_files, [
+  'app/etc/env.php',
+  'var/.setup_cronjob_status',
+  'var/.update_cronjob_status',
+  'sitemap.xml'
+]
+
+set :linked_dirs, [
+  'pub/media', 
+  'var/backups', 
+  'var/composer_home', 
+  'var/importexport', 
+  'var/import_history', 
+  'var/log',
+  'var/session', 
+  'var/tmp'
+]
 ```
 
+If you would like to customize the linked files or directories for your project, you can copy either one or both of the above arrays into the `config/deploy.rb` or `config/deploy/*.rb` files and tweak them to fit your project's needs.
+
 ### Magento 2 Deploy Routine
 
-A pre-built deploy routine is available out-of-the-box. This can be overriden on a per-project basis by including only the Magento 2 specific tasks and defining your own `deploy.rake` file under `lib/capistrano/tasks` in your projects capistrano install location.
+A pre-built deploy routine is available out-of-the-box. This can be overriden on a per-project basis by including only the Magento 2 specific tasks and defining your own `deploy.rake` file under `lib/capistrano/tasks` in your projects Capistrano install location.
 
 To see what process the built-in routine runs, take a look at the included rake file here: https://github.com/davidalger/capistrano-magento2/blob/master/lib/capistrano/tasks/deploy.rake
 
+## Server Configuration
+
+### Web Server Root Path
+
+Before deploying with Capistrano, you must update each of your web servers to point to a `current` directory inside of the `:deploy_to` directory. For example: `/var/www/html/current` Refer to the [Capistrano Structure](http://capistranorb.com/documentation/getting-started/structure/) to learn more about Capistrano's folder structure.
+
+### Create Linked Files
+
+Capistrano assumes that the `:linked_files` files will exist, so before you deploy for the first time, you need to create those files. On each of your web servers, create them using a command like this:
+
+```shell
+$ cd /var/www/html
+$ mkdir -p shared/var shared/app/etc
+$ touch shared/app/etc/env.php shared/var/.setup_cronjob_status shared/var/.update_cronjob_status shared/sitemap.xml
+```
+
 ## Magento Specific Tasks
 
-All Magento 2 tasks used by the built-in `deploy.rake` file as well as some additional commands are implimented and exposed to the end-user for use directly via the cap tool. You can also see this list by running `cap -T` from your shell.
+All Magento 2 tasks used by the built-in `deploy.rake` file as well as some additional commands are implemented and exposed to the end-user for use directly via the cap tool. You can also see this list by running `cap -T` from your shell.
 
 | cap command                           | what it does                                       |
 | ------------------------------------- | -------------------------------------------------- |
@@ -100,10 +182,6 @@ All Magento 2 tasks used by the built-in `deploy.rake` file as well as some addi
 | magento:setup:static-content:deploy   | Deploys static view files                          |
 | magento:setup:upgrade                 | Run the Magento upgrade process                    |
 
-## Using Capistrano
-
-For inrformation on how to use Capistrano and setup deployment take a look at the [Capistrano documentation](http://capistranorb.com) and [README](https://github.com/capistrano/capistrano/blob/master/README.md) file.
-
 ## Terminal Notifier on OS X
 This gem specifies [terminal-notifier](https://rubygems.org/gems/terminal-notifier) as a dependency in order to support notifications on OS X via an optional include. To use the built-in notifications, add the following line to your `Capfile`:
 
@@ -113,7 +191,7 @@ require 'capistrano/magento2/notifier'
 
 ## Development
 
-After checking out the repo, run `bundle install` to install dependencies. Make the neccesary changes, then run `bundle exec rake install` to install a modified version of the gem on your local system.
+After checking out the repo, run `bundle install` to install dependencies. Make the necessary changes, then run `bundle exec rake install` to install a modified version of the gem on your local system.
 
 To release a new version, update the version number in `capistrano/magento2/version.rb`, merge all changes to master, and then run `bundle exec rake release`. This will create a git tag for the version (the tag will apply to the current HEAD), push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 

data/lib/capistrano/magento2/version.rb

@@ -9,6 +9,6 @@
 
 module Capistrano
   module Magento2
-    VERSION = '0.2.0'
+    VERSION = '0.2.1'
   end
 end

data/lib/capistrano/tasks/deploy.rake

@@ -15,8 +15,10 @@ namespace :deploy do
       invoke 'magento:setup:static-content:deploy'
       invoke 'magento:setup:di:compile'
       invoke 'magento:setup:permissions'
-      within current_path do
-        execute :magento, 'maintenance:enable'
+      if test '-d #{current_path}'
+        within current_path do
+          execute :magento, 'maintenance:enable'
+        end
       end
       invoke 'magento:maintenance:enable'
       invoke 'magento:setup:upgrade'
@@ -26,7 +28,7 @@ namespace :deploy do
   task :published do
     on release_roles :all do
       invoke 'magento:cache:flush'
-      invoke 'magento:cache:varnish:ban'    # TODO: this should not be needed after magento/magento2#3339 is released
+      invoke 'magento:cache:varnish:ban'    # TODO: This invocation should not be needed post magento/magento2#3339
       invoke 'magento:maintenance:disable'
     end
   end
@@ -35,7 +37,7 @@ namespace :deploy do
     on release_roles :all do
       invoke 'magento:maintenance:disable'
       invoke 'magento:cache:flush'
-      invoke 'magento:cache:varnish:ban'
+      invoke 'magento:cache:varnish:ban'    # TODO: This invocation should not be needed post magento/magento2#3339
     end
   end
 end

data/lib/capistrano/tasks/magento.rake

@@ -56,6 +56,7 @@ namespace :magento do
     end
   
     namespace :varnish do
+      # TODO: Document what the magento:cache:varnish:ban task is for and how to use it. See also magento/magento2#4106
       desc 'Add ban to Varnish for url(s)'
       task :ban do
         on release_roles :all do

data/lib/capistrano/tasks/notifier.rake

@@ -42,6 +42,7 @@ end
 
 namespace :load do
   task :defaults do
+    # TODO: Document the :deploy_warn_stages option
     set :deploy_warn_stages, fetch(:deploy_warn_stages, []).push('prod', 'production')
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: capistrano-magento2
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - David Alger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-27 00:00:00.000000000 Z
+date: 2016-05-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capistrano