Browse files

Update readme and add changelog

  • Loading branch information...
1 parent 30783bf commit a11ff12740da298fe1294db5c330439e492f363e @peterjmit peterjmit committed Jan 16, 2016
Showing with 113 additions and 63 deletions.
  1. +32 −0
  2. +81 −63
@@ -0,0 +1,32 @@
+# Capistrano Symfony 1.x Changelog
+## `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:
+* 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
@@ -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.
-# 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`
@@ -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
+# 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]( and [the file permission capistrano plugin]( 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:
- 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.
namespace :deploy do
task :migrate do
- invoke 'symfony:console', 'doctrine:migrations:migrate', '--no-interaction'
+ symfony_console('doctrine:migrations:migrate', '--no-interaction')
-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
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

0 comments on commit a11ff12

Please sign in to comment.