capistrano-templating 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 60357a96aa386dd2222ab229ec464a20d3a1263c
+  data.tar.gz: 6602c4b6e8cbd8da3ddee11ef69cdcfc45de2a79
+SHA512:
+  metadata.gz: 959f6f8b53eee0504a558c30862c6b7a385a5865b9522027b9fc04bc79b3577b220de944f4baa7e74c483e5fcb63f16df3e6002d44f958752ac5e283d77755cb
+  data.tar.gz: 41817232dd64c57c632fe97ad3b1705789a79a01cce60eb8e953120207ade4d430de4646f5f8948de2e9e1a1f755bc032352a96deab1891438f660931d40aa98

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in capistrano-template.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Xavier Priour
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,119 @@
+# Capistrano::Templating
+
+A [Capistrano](http://capistranorb.com/) gem to generate files from templates on deployment.
+
+In a typical application, configuration files contain lots of code common to all stages, and a few differences (like database or mail server and credentials).
+This gem lets you put common code in ERB templates,
+and manage variable parts using Capistrano variables (`set :var_name, 'value'`)
+or [capistrano-secret](https://github.com/xavierpriour/capistrano-secret).
+
+This is especially useful to generate configuration files for various server elements, based on DRY secret files + single template for each configuration file.
+
+
+## Quick start
+
+In a shell:
+```bash
+gem install capistrano-templating
+echo "require 'capistrano/templating'" >> Capfile
+mkdir -p lib/capistrano/templates
+echo "Deployed to <%= fetch(:stage) %> at <%= Time.new() %>" > lib/capistrano/templates/deploy.html.erb
+```
+
+Then in `deploy.rb`:
+```ruby
+set_template 'www/deploy.html', 'deploy.html.erb';
+```
+
+
+## Features
+
+Capistrano::Templating advantages:
+* all common code is centralized in the template: no duplication (DRY).
+* file can be generated anywhere (even in multiple places), with any name.
+* any file format can be generated.
+
+When combined with [capistrano-secret](https://github.com/xavierpriour/capistrano-secret),
+enables perfect separation of responsibilities:
+* all secret information in easy-to-read JSON, stored in dedicated folder
+* syntax wrapping (for configuration file, deployment pages, or else) concentrated in templates
+
+In details:
+* 2-step generation: files are generated in a separate build local folder, then copied into release dir. This allows local view of the generated files for debugging.
+* generated file path and name is specified separately from template file. This lets you put all templates in the same folder, yet dispatch generated files everywhere.
+
+Compared to [capistrano-template](https://github.com/faber-lotto/capistrano-template) gem,
+Capistrano::Templating uses a declarative syntax (`set_template` then automatic generation),
+whereas capistrano-template uses an imperative syntax (ask for render using `template`).
+Pick the one that suits you best!
+
+
+## Requirements
+
+* [Capistrano 3](http://capistranorb.com/)
+
+All dependencies are listed in the .gemspec file so if using `bundler` you just need to `bundle install` in your project directory.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+```
+gem 'capistrano-templating'
+```
+
+And then execute:
+```bash
+bundle
+```
+
+Or install it yourself as:
+```bash
+gem install capistrano-templating
+```
+
+
+## Usage
+
+An example application is included in the `example` folder.
+
+Include gem in your `Capfile`:
+```ruby
+require 'capistrano/templating'
+```
+
+Create directory where templates will be stored.
+Default is `lib/capistrano/template`, to use a different one define `template_src_dir` in `deploy.rb`:
+```ruby
+set :template_src_dir, 'new/template/dir'
+```
+
+Define directory where generated files will be stored.
+Default is `build`, to use a different one define `template_build_dir` in `deploy.rb`:
+```ruby
+set :template_build_dir, 'new/build/dir'
+```
+Ensure the build directory stays out of repository (for git, add it to `.gitignore`):
+```bash
+echo 'build' >> .gitignore
+```
+
+Then in the template directory, create one ERB file per model of file needed.
+As a naming convention, we suggest `name_and_ext_of_target.erb`. For example, `.htaccess.erb` to generate `.htaccess`.
+
+Finally, declare the files to generate in `deploy.rb` or the stage files (like `production.rb`):
+```ruby
+set_template 'path/to/result.html', 'template.html.erb'
+```
+Destination filepaths are relative to application root folder, template paths are relative to template directory.
+
+At the end of deployment, capistrano will automatically generate the files in the local build dir (including sub-directory creation),
+then upload them in the remote release directories.
+
+
+## Contributing
+1. Fork it ( https://github.com/xavierpriour/capistrano-templating/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/capistrano-templating.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'capistrano/templating/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "capistrano-templating"
+  spec.version       = Capistrano::Templating::VERSION
+  spec.authors       = ["Xavier Priour"]
+  spec.email         = ["xavier.priour@bubblyware.com"]
+  spec.summary       = %q{Capistrano gem to generate files from templates on deployment}
+#  spec.description   = %q{TODO: Write a longer description. Optional.}
+  spec.homepage      = "https://github.com/xavierpriour/capistrano-templating"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+
+  spec.add_dependency "capistrano", "~> 3"
+end

data/example/.gitignore

@@ -0,0 +1,5 @@
+# do not add secrets to repository
+config/secret
+
+# do not add files built from templates to repository
+build

data/example/Capfile

@@ -0,0 +1,12 @@
+# Load DSL and Setup Up Stages
+require 'capistrano/setup'
+
+# Includes default deployment tasks
+require 'capistrano/deploy'
+
+# Includes tasks from other gems included in your Gemfile
+require 'capistrano/secret'
+require 'capistrano/templating'
+
+# Loads custom tasks from `lib/capistrano/tasks' if you have any defined.
+Dir.glob('lib/capistrano/tasks/*.cap').each { |r| import r }

data/example/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+gem "capistrano-secret", require: false
+gem "capistrano-templating", require: false

data/example/config/deploy.rb

@@ -0,0 +1,33 @@
+set_template 'www/deploy.html', 'deploy.html.erb'
+set_template 'www/php/config.php', 'config.php.erb'
+
+
+
+set :application, 'capistrano_example_app'
+
+set :scm, :git
+set :repo_url, 'https://github.com/xavierpriour/capistrano-template.git'
+
+
+namespace :deploy do
+
+  desc 'Restart application'
+  task :restart do
+    on roles(:app), in: :sequence, wait: 5 do
+      # Your restart mechanism here, for example:
+      # execute :touch, release_path.join('tmp/restart.txt')
+    end
+  end
+
+  after :publishing, :restart
+
+  after :restart, :clear_cache do
+    on roles(:web), in: :groups, limit: 3, wait: 10 do
+      # Here we can do anything such as:
+      # within release_path do
+      #   execute :rake, 'cache:clear'
+      # end
+    end
+  end
+
+end

data/example/config/deploy/local.rb

@@ -0,0 +1,3 @@
+server 'localhost', user: 'xavier', roles: %w{web app}
+
+set :deploy_to, "/home/xavier/tmp/cap/#{fetch(:application)}"

data/example/config/deploy/production.rb

@@ -0,0 +1 @@
+server 'example.com', user: 'deploy', roles: %w{web app}, my_property: :my_value

data/example/lib/capistrano/templates/config.php.erb

@@ -0,0 +1,3 @@
+<?php
+  define('DSN', '<%= "mysql://#{secret('db.user')}:#{secret('db.pass')}@#{secret('db.host')}/#{secret('db.name')}?charset=utf8" %>');
+?>

data/example/lib/capistrano/templates/deploy.html.erb

@@ -0,0 +1,5 @@
+<html>
+  <body>
+Deployed to <%= fetch(:stage) %> at <%= Time.new() %>
+  </body>
+</html>

data/lib/capistrano/templating.rb

@@ -0,0 +1,9 @@
+require "capistrano/templating/version"
+
+module Capistrano
+  module Templating
+    # Your code goes here...
+  end
+end
+
+load File.expand_path('../templating/tasks/template.cap', __FILE__)

data/lib/capistrano/templating/tasks/template.cap

@@ -0,0 +1,77 @@
+def set_template(file, template)
+  unless fetch(:templates)
+    set :templates, {}
+  end
+  fetch(:templates)[file] = template
+end
+
+namespace :template do
+  def template_dir()
+    return fetch(:template_src_dir) || 'lib/capistrano/templates'
+  end
+  
+  def build_dir()
+    return fetch(:template_build_dir) || 'build'
+  end
+  
+  
+  desc <<-DESC
+    Generate all templates defined in :templates.
+    
+    1. generate in local build dir, with destination names
+    2. upload to remote release dir, merging with non-generated files
+    
+    We used to upload in build dir then symlink, but switched to direct merge to support hosts without symlink support.
+DESC
+  task :generate do
+    templates_list = fetch(:templates, {});
+    
+    templates_list.each do |dst, src|
+      # splits destination in optional relative dir / filename
+      m = /(.*\/)?([^\/]+)$/.match(dst)
+      dst_rel_dir = m[1]
+      dst_file = m[2]
+      #create local build dirs as needed
+      build_dir = "#{build_dir()}/#{dst_rel_dir}"
+      %x(mkdir -p #{build_dir})
+      build_filepath = "#{build_dir}#{dst_file}"
+      # get template and render it
+      template_filepath = "#{template_dir()}/#{src}"
+      template = File.read(template_filepath)
+      File.open(build_filepath, 'w+') do |f|
+        f.write(ERB.new(template).result(binding))
+      end
+      
+      on roles(:all) do |host|
+        # create remote build dir
+        if dst_rel_dir
+          execute "mkdir -p #{release_path.to_s}/#{dst_rel_dir}"  
+        end
+        upload! build_filepath, release_path.to_s+'/'+dst
+      end
+    end
+  end
+  
+  desc "cleanup everything that was built"
+  task :clear_dir do
+    # clean all build artifacts
+    %x(rm -rf #{build_dir()})
+  end
+  
+  task :remove do
+    templates_list = fetch(:templates, {});
+    templates_list.each do |dst, src|
+      on roles(:all) do |host|
+        # remove link
+        link = "#{release_path.to_s}/#{dst}"
+        if test("[ -f #{link} ]")
+          execute "rm #{link}"
+        end
+        #todo remove any dir that is now empty...  
+      end  
+    end
+  end
+end
+
+before 'deploy:starting', 'template:clear_dir'
+after 'deploy:publishing', 'template:generate'

data/lib/capistrano/templating/version.rb

@@ -0,0 +1,5 @@
+module Capistrano
+  module Templating
+    VERSION = "1.0.1"
+  end
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: capistrano-templating
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Xavier Priour
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-06-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: capistrano
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: 
+email:
+- xavier.priour@bubblyware.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- capistrano-templating.gemspec
+- example/.gitignore
+- example/Capfile
+- example/Gemfile
+- example/config/deploy.rb
+- example/config/deploy/local.rb
+- example/config/deploy/production.rb
+- example/config/secret/local.json
+- example/config/secret/production.json
+- example/lib/capistrano/templates/config.php.erb
+- example/lib/capistrano/templates/deploy.html.erb
+- lib/capistrano/templating.rb
+- lib/capistrano/templating/tasks/template.cap
+- lib/capistrano/templating/version.rb
+homepage: https://github.com/xavierpriour/capistrano-templating
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Capistrano gem to generate files from templates on deployment
+test_files: []