Capistrano::Laravel

Deploy Laravel applications with Capistrano v3.*

Installation

If managing your Capistrano deploy as a ruby project, add this line to your application's Gemfile:

gem 'capistrano', '~> 3.0.0'
gem 'capistrano-laravel'

And then execute:

bundle

Or install it yourself as:

gem install capistrano-laravel

Setting up Capistrano

After installing Capistrano, you can use it to initialize a skeleton configuration. To setup Capistrano, please follow the documentation provided on their website:

http://capistranorb.com/documentation/getting-started/preparing-your-application/

This will generate the following files:

.
├── Capfile                # Used to manage Capistrano and its dependencies
├── config
│   ├── deploy
│   │   ├── production.rb  # Configuration for production environment
│   │   └── staging.rb     # Configuration for staging environment
│   └── deploy.rb          # Common configuration for all environments
└── lib
    └── capistrano
        └── tasks          # Customized Capistrano tasks for your project

Usage

Require the module in your Capfile:

require 'capistrano/laravel'

Configuration

The gem makes the following configuration variables available (shown with defaults).

# Which roles to consider as laravel roles
set :laravel_roles, :all

# The artisan flags to include on artisan commands by default
set :laravel_artisan_flags, "--env=#{fetch(:stage)}"

# Which roles to use for running migrations
set :laravel_migration_roles, :all

# The artisan flags to include on artisan commands by default when running migrations
set :laravel_migration_artisan_flags, "--force --env=#{fetch(:stage)}"

# The version of laravel being deployed
set :laravel_version, 5.3

# Whether to upload the dotenv file on deploy
set :laravel_upload_dotenv_file_on_deploy, true

# Which dotenv file to transfer to the server
set :laravel_dotenv_file, './.env'

# The user that the server is running under (used for ACLs)
set :laravel_server_user, 'www-data'

# Ensure the dirs in :linked_dirs exist?
set :laravel_ensure_linked_dirs_exist, true

# Link the directores in laravel_linked_dirs?
set :laravel_set_linked_dirs, true

# Linked directories for a standard Laravel 4 application
set :laravel_4_linked_dirs, [
  'app/storage'
]

# Linked directories for a standard Laravel 5 application
set :laravel_5_linked_dirs, [
  'storage'
]

# Ensure the paths in :file_permissions_paths exist?
set :laravel_ensure_acl_paths_exist, true

# Set ACLs for the paths in laravel_acl_paths?
set :laravel_set_acl_paths, true

# Paths that should have ACLs set for a standard Laravel 4 application
set :laravel_4_acl_paths, [
  'app/storage',
  'app/storage/public',
  'app/storage/cache',
  'app/storage/logs',
  'app/storage/meta',
  'app/storage/sessions',
  'app/storage/views'
]

# Paths that should have ACLs set for a standard Laravel 5 application
set :laravel_5_acl_paths, [
  'bootstrap/cache',
  'storage',
  'storage/app',
  'storage/app/public',
  'storage/framework',
  'storage/framework/cache',
  'storage/framework/sessions',
  'storage/framework/views',
  'storage/logs'
]

Tasks

The following tasks are added to your deploy automagically when adding capistrano/laravel to your deploy.

before 'deploy:starting', 'laravel:resolve_linked_dirs'
before 'deploy:starting', 'laravel:resolve_acl_paths'
after  'deploy:starting', 'laravel:ensure_linked_dirs_exist'
before 'deploy:updating', 'laravel:ensure_acl_paths_exist'
before 'deploy:updated',  'deploy:set_permissions:acl'
before 'deploy:updated',  'laravel:upload_dotenv_file'
after  'composer:run',    'laravel:storage_link'
after  'composer:run',    'laravel:optimize'

Task Descriptions

# Determine which folders, if any, to use for linked directories.
invoke 'laravel:resolve_linked_dirs'

# Determine which paths, if any, to have ACL permissions set.
invoke 'laravel:resolve_acl_paths'

# Ensure that linked dirs exist.
invoke 'laravel:ensure_linked_dirs_exist'

# Ensure that ACL paths exist.
invoke 'laravel:ensure_acl_paths_exist'

# Upload dotenv file for release.
invoke 'laravel:upload_dotenv_file'

# Execute a provided artisan command.
# Replace :command_name with the command to execute
invoke 'laravel:artisan[:command_name]'

# Create a cache file for faster configuration loading
invoke 'laravel:config_cache'

# Create a route cache file for faster route registration
invoke 'laravel:route_cache'

# Optimize the framework for better performance.
invoke 'laravel:optimize'

# Create a symbolic link from "public/storage" to "storage/app/public"
invoke 'laravel:storage_link'

# Run the database migrations.
invoke 'laravel:migrate'

# Rollback the last database migration.
invoke 'laravel:migrate_rollback'

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/capistrano/laravel.

License

The gem is available as open source under the terms of the MIT License.