From a11ff12740da298fe1294db5c330439e492f363e Mon Sep 17 00:00:00 2001 From: Peter Mitchell Date: Sat, 16 Jan 2016 00:47:43 +0000 Subject: [PATCH] Update readme and add changelog --- CHANGELOG.md | 32 ++++++++++++ README.md | 144 +++++++++++++++++++++++++++++---------------------- 2 files changed, 113 insertions(+), 63 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..15af42e --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,32 @@ +# Capistrano Symfony 1.x Changelog + + +## `1.0.0.rc1` + +https://github.com/capistrano/symfony/compare/0.4.0...1.0.0.rc1 + +* Use file permissions gem v1 +* Symfony 3 directory structure is on by default +* Remove `use_set_permission` variable +* Remove `web/uploads` as a default linked directory +* Remove support for Assetic (see: https://github.com/symfony/symfony-standard/pull/860) +* Support SensioLabsDistributionBundle 5 (#49) +* Support Symfony 3 directory structure (#31) +* `build_bootstrap_path` is now a DSL method +* `symfony_console` is now a DSL method (use instead of `invoke "symfony:console"`) +* Paths DSL file has been moved to `lib/capistrano/dsl/symfony.rb` +* Deprecated `symfony:command` task has been removed +* `webserver_user` variable has been removed (#40) +* Various typo fixes + +### Contributors + +Thanks to everyone who has filed an issue or submitted a fix + + * @kriswallsmith + * @zaerl + * @sandermarechal + * @pborreli + * @wideawake + * @issei-m + * @alafon diff --git a/README.md b/README.md index 00d4e83..e73cdf8 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,6 @@ # Capistrano::Symfony -Symfony 2 (standard edition) specific tasks for Capistrano v3 -(inspired by [capifony][2]) +Symfony 2 (standard edition) specific tasks for Capistrano v3 (inspired by [capifony][2]). It leverages the following capistrano tasks to deploy a Symfony app @@ -12,8 +11,8 @@ It leverages the following capistrano tasks to deploy a Symfony app ``` # Gemfile -gem 'capistrano', '~> 3.1' -gem 'capistrano-symfony', '~> 0.1', :github => 'capistrano/symfony' +gem 'capistrano', '~> 3.4' +gem 'capistrano-symfony', '~> 1.0.0.rc1' ``` ## Usage @@ -25,79 +24,74 @@ Require capistrano-symfony in your cap file require 'capistrano/symfony' ``` + ### Settings -capistrano-symfony exposes the following settings (displayed with defaults): +If you are using an un-modified symfony-standard edition, version 3 then you do not need to change/add anything to your `deploy.rb` other than what is required from Capistrano. + +We do however expose the following settings (shown with default evaluated values) that can be modified to suit your project. Please refer to `lib/capistrano/symfony/defaults.rb` to see exactly how the defaults are set up. + ```ruby -# Symfony environment +# Symfony console commands will use this environment for execution set :symfony_env, "prod" -# Symfony application path -set :app_path, "app" - -# Symfony web path -set :web_path, "web" +# Set this to 2 for the old directory structure +set :symfony_directory_structure, 3 +# Set this to 4 if using the older SensioDistributionBundle +set :sensio_distribution_version, 5 -# Symfony log path -set :log_path, fetch(:app_path) + "/logs" +# symfony-standard edition directories +set :app_path, "app" +set :web_path, "web" +set :var_path, "var" +set :bin_path, "bin" -# Symfony cache path -set :cache_path, fetch(:app_path) + "/cache" +# The next 3 settings are lazily evaluated from the above values, so take care +# when modifying them +set :app_config_path, "app/config" +set :log_path, "var/logs" +set :cache_path, "var/cache" -# Symfony config file path -set :app_config_path, fetch(:app_path) + "/config" +set :symfony_console_path, "bin/console" +set :symfony_console_flags, "--no-debug" -# Controllers to clear +# Remove app_dev.php during deployment, other files in web/ can be specified here set :controllers_to_clear, ["app_*.php"] -# Files that need to remain the same between deploys -set :linked_files, [] - -# Dirs that need to remain the same between deploys (shared dirs) -set :linked_dirs, [fetch(:log_path), fetch(:web_path) + "/uploads"] - -# Dirs that need to be writable by the HTTP Server (i.e. cache, log dirs) -set :file_permissions_paths, [fetch(:log_path), fetch(:cache_path)] - -# Name used by the Web Server (i.e. www-data for Apache) -set :file_permissions_users, ['www-data'] - -# Name used by the Web Server (i.e. www-data for Apache) -set :webserver_user, "www-data" - -# Method used to set permissions (:chmod, :acl, or :chgrp) -set :permission_method, false - -# Execute set permissions -set :use_set_permissions, false - -# Symfony console path -set :symfony_console_path, fetch(:app_path) + "/console" +# asset management +set :assets_install_path, "web" +set :assets_install_flags, '--symlink' -# Symfony console flags -set :symfony_console_flags, "--no-debug" +# Share files/directories between releases +set :linked_files, [] +set :linked_dirs, ["var/logs"] -# Assets install path -set :assets_install_path, fetch(:web_path) +# Set correct permissions between releases, this is turned off by default +set :file_permissions_paths, ["var"] +set :permission_method, false +``` -# Assets install flags -set :assets_install_flags, '--symlink' +#### Using this plugin with the old Symfony 2 directory structure and SensioDistributionBundle <= 4 -# Assetic dump flags -set :assetic_dump_flags, '' +Add the following to `deploy.rb` to use the old directory structure -fetch(:default_env).merge!(symfony_env: fetch(:symfony_env)) +``` +# deploy.rb +set :symfony_directory_structure, 2 +set :sensio_distribution_version, 4 ``` +If you are upgrading this gem and have modified `linked_dirs` or "advanced" variables such as `log_path` then you will need to update those accordingly + ### Flow capistrano-symfony hooks into the [flow][1] offered by capistrano. It adds to that flow like so -* ```symfony:create_cache_dir``` -* ```symfony:set_permissions``` -* ```symfony:cache:warmup``` -* ```symfony:clear_controllers``` +* `symfony:create_cache_dir` +* `symfony:set_permissions` +* `symfony:cache:warmup` +* `symfony:clear_controllers` ``` deploy @@ -125,16 +119,38 @@ deploy |__ deploy:log_revision ``` +### File permissions + +Set the `permission_method` variable to one of `:chmod`, `:acl`, or `:chgrp` in your `deploy.rb` to handle the common scenario of a web user and the deploy user being different. + +Both will need access to the files/directories such as `var/cache` and `web/uploads` (if you handle uploads). Set `file_permissions_users` to your webserver user + +Example: + +``` +# deploy.rb + +set :permission_method, :acl +set :file_permissions_users, ["nginx"] +set :file_permissions_paths, ["var", "web/uploads"] +``` + +Please note that `:acl` requires that `setfacl` be available on your deployment target + +See [the symfony documentation](http://symfony.com/doc/current/book/installation.html#checking-symfony-application-configuration-and-setup) and [the file permission capistrano plugin](https://github.com/capistrano/file-permissions) for reference + ### Integrated common tasks -The folowing common tasks are already integrated: -* ```symfony:assets:install``` -* ```symfony:assetic:dump``` +The following common tasks are available: + +* `symfony:assets:install` +* `symfony:build_bootstrap` - useful if you disable composer + +So you can use them with hooks in your project's `deploy.rb` like this: -So you can use them with hooks like this: ```ruby - after 'deploy:updated', 'symfony:assets:install' - after 'deploy:updated', 'symfony:assetic:dump' +after 'deploy:updated', 'symfony:assets:install' +before 'deploy:updated', 'symfony:build_bootstrap' ``` ### Using the Symfony console @@ -148,17 +164,19 @@ project you may want to run migrations during a deploy. ```ruby namespace :deploy do task :migrate do - invoke 'symfony:console', 'doctrine:migrations:migrate', '--no-interaction' + symfony_console('doctrine:migrations:migrate', '--no-interaction') end end ``` -You can also apply role filter on your commands by passing a fourth parameter. +If you want to execute a command on a host with a given role you can use the Capistrano `on` DSL, additionally using `within` from Capistrano will change the directory ```ruby namespace :deploy do task :migrate do - invoke 'symfony:console', 'doctrine:migrations:migrate', '--no-interaction', 'db' + on roles(:db) do + symfony_console('doctrine:migrations:migrate', '--no-interaction') + end end end ```