Skip to content

Commit

Permalink
Update readme and add changelog
Browse files Browse the repository at this point in the history
  • Loading branch information
@peterjmit
peterjmit committed Jan 16, 2016
1 parent 30783bf commit a11ff12
Show file tree
Hide file tree
Showing 2 changed files with 113 additions and 63 deletions.
32 changes: 32 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -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
144 changes: 81 additions & 63 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
```
Expand Down

0 comments on commit a11ff12

Please sign in to comment.