SilverStripe-Capistrano has been tested with version
2.2.3 of ruby. To install
2.2.3 with RVM use the below command
rvm install 2.2.3 rvm use 2.2.3
Note: This script should work with other versions of Ruby, your results may vary.
SilverStripe-Capistrano requires Capistrano version
3.4.0 which can be installed using the below command`
gem install capistrano -v 3.4.0
Preparing your project
Commit your code to GIT - before we can deploy our code it needs to be committed into GIT onto a branch we have access to.
It is also recommended that you add the contents of
gitignore.example to your
Copying SilverStripe-Capistrano files into your project
Using the script below, from the root or your project you can automate the download of our Capistrano config.
NOTE: The below script will OVERWRITE the contents of the files listed below which already exist in your project.
mkdir -p config mkdir -p config/deploy curl -O https://raw.githubusercontent.com/mattrayner/silverstripe-capistrano/master/Gemfile curl -O https://raw.githubusercontent.com/mattrayner/silverstripe-capistrano/master/Capfile cd config curl -O https://raw.githubusercontent.com/mattrayner/silverstripe-capistrano/master/config/deploy.rb cd deploy curl -O https://raw.githubusercontent.com/mattrayner/silverstripe-capistrano/master/config/deploy/staging.rb curl -O https://raw.githubusercontent.com/mattrayner/silverstripe-capistrano/master/config/deploy/production.rb cd ../..
Alternatively you can copy each of the files into your repository manually. This is the recommended approach if you have any file clashes.
If you are unfamiliar with Capistrano, it's recommended that you read over the documentation on the Capistrano website. This will give you a good overview of how it works as well as details on how to properly configure a Capistrano installation.
Start off by configuring the
production.rb files in the
/config/deploy directory. Feel free to add or remove server configuration files as needed. Just be sure and set appropriate config names at the top (ie.
set :prod, :production).
There are a few custom variables at the top that differ from the default Capistrano configuration. These are necessary to allow the SilverStripe tasks to work properly.
website_url to the full web address of your application. This is used to recache the homepage of your site after a build.
curl_command to the desired flush web address for your application. This will be used in an attempt to flush your application's front-end cache.
Set the four database variables for the database host, name, username, and password of the MySQL database used for your SilverStripe application. This will allow backup and restore tasks to be performed during a deploy or rollback.
It’s recommended that a SSH key be setup rather than adding a password to the config files. Visit the Github site for help on generating a SSH key.
Continue configuration by updating the
deploy.rb file in the
/config directory. If needed, use the Preparing Your Application page on the Capistrano website for reference. The
deploy_to variables are required by default.
deploy_to variable should point to where you want your Capistrano files to live on the server. If you're managing multiple applications on the same server then you might want to deploy them based on application name. I typically create a
capistrano directory that's just above where all the site files live. Where and how you wish to manage your Capistrano deploys is entirely up to you though.
Towards the bottom of the
deploy.rb file there are two variables,
db_backup_dir. It's recommended that you set these explicitly to avoid errors.
It's also recommended that you check the
linked_dirs to ensure that they include the files and directories that are not tracked by the repo. These files and directories will need to be added to the
shared directory, which we'll get to in a sec.
Remote Server Configuration
You'll need to setup the directory where Capistrano files will live on the server. Be sure that this matches what you set for the
deploy_to variable in the
deploy.rb config file.
There are a number of directories you should create so that capistrano can work correctly. Run the below command to automate this process
ENVIRONMENT with one of your server configurations i.e.
In order for
sake to run a
dev/build on the server, you'll need to update your
_ss_environment.php config so that it includes the
// This is used by sake to know which directory points to which URL global $_FILE_TO_URL_MAPPING; $_FILE_TO_URL_MAPPING[realpath('/var/www/public_html')] = 'http://www.yoursite.com';
You will need to replace
http://www.yoursite.com with the correct details for your setup.
More information about this can be found on the SilverStripe Documentation site.
OPTIONAL environment $_GET config
This is an optional and not very secure addition you can make to your
_ss_environment.php file. It will allow you to use
?flush=all in dev move even on production installations. This is a less error-prone way of flushing the front-end cache on a production server.
It is important however that you also consider the downsides. Useing the below code makes deploying a bit easier but also opens your website up to possible vulnerabilities.
Any page can be viewed in
dev mode. This is done entirely at your own risk and is not strictly required.
$env_type = isset($_GET['env_type']) ? $_GET['env_type'] : 'test'; define('SS_ENVIRONMENT_TYPE', $env_type);
To make sure that Git (and your server) is setup properly for a successful deploy, it’s recommended that a
deploy:check be executed prior to deploying for the first time:
cap staging deploy:check
To run a deploy on either staging or production, simply call Capistrano for the environment of your choice:
cap production deploy
Don’t forget to import in any changes to the database! Be sure and test the site to ensure that everything is working as it should.
The full-ish changelog is available in CHANGELOG.md
SilverStripe-Capistrano requires the following:
- Ruby (tested with 2.2.3)
- Capistrano (designed for 3.4.0)
- Curl (for install script automation)
- Composer (required server-side to install SilverStripe)
A list (in no particular order) or future feature ideas:
- Automation script.
- Some kind of php/ruby/sh script that will automatically setup SilverStripe-Capistrano within a project.
- Custom GEM.
- Instead of adding Capistrano to your GEMFILE, we'll use our own which depends on a certain Capistrano version.
If you wish to submit a bug fix or feature, you can create a pull request and it will be merged pending a code review.
- Clone it
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Add some feature')
- Push to the branch (git push origin my-new-feature)
- Create a new Pull Request
SilverStripe-Capistrano is licensed under the MIT License.