by capistrano

capistrano / laravel

Gem for deploying Laravel projects with capistrano v3.*

209 Stars 68 Forks Last release: Not found MIT License 49 Commits 12 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:


Deploy Laravel applications with Capistrano v3.*


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:


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:

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


Require the module in your

require 'capistrano/laravel'


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' ]


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'


After checking out the repo, run

to install dependencies. Then, run
rake spec
to run the tests. You can also run
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
, and then run
bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the
file to


Bug reports and pull requests are welcome on GitHub at


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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.