Compiling and deploying Sass stylesheets
Clone this wiki locally
If you're using Sass and/or Compass in your projects then this is the page for you. We've added some sassy goodness to the capistrano-ash recipes to help make compiling and deploying the assets to your remote servers a breeze (well at least PHP projects — still can't beat Rails' asset pipeline and capistrano's deploy/assets tasks).
The goals we wanted to achieve with our Compass/Sass tasks were:
- compile Sass stylesheets for one or more "themes"
- make it easier for developers to compile their Sass stylesheets into minified and compressed CSS ready for production use
- facilitate uploading of compiled stylesheets to the remote web servers
- automate the entire process (compiling, uploading, fixing permissions, etc.)
- "bake" the feature into all the recipes
- make the entire feature optional (if you don't use Sass or Compass we don't force you—we'll just skip the tasks)
Compile Sass stylesheets for one or more themes
# -------------------------------------------- # Compile Sass stylesheets and upload to servers # # ONLY RUNS IF YOU HAVE SET :compass_watched_dirs # # :compass_watched_dirs can either be a string or an array # # Example: # # Use the array syntax if you compass watch several directories: # set :compass_watched_dirs, ["sites/all/themes/ash", "sites/all/themes/my_custom_theme"] # # Use the string syntax if you only compass watch one directory: # set :compass_watched_dirs, "sites/all/themes/ash" # # If you name your public stylesheets directory something # other than "stylesheets" than you can specify the name of # the directory with the :stylesheets_dir_name variable # # Examples (both assume your compiled stylesheets exist within your :compass_watched_dirs): # # If your Sass compiles to your assets/css directory (i.e., `sites/all/themes/ash/assets/css`): # set :stylesheets_dir_name, "assets/css" # # If your Sass compiles to a separate directory (i.e., `sites/all/themes/ash/styles`): # set :stylesheets_dir_name, "styles" # -------------------------------------------- set :compass_watched_dirs, "sites/all/themes/ash" set :stylesheets_dir_name, "assets/css"
You may define
:compass_watched_dirs as a string or an array of strings to specify the location of your Sass stylesheets.
:compass_watched_dirs is not set, then all
compass tasks will be skipped.
Define where compiled stylesheets are located
By default, we assume your Sass stylesheets are compiled into a directory called
stylesheets and this directory exists within each of the
sites/all/themes/ash/stylesheets) you specified earlier. If this is not the case (i.e., the compiled CSS styles are actually stored at
sites/all/themes/ash/assets/css) then simply specify the correct location for the
:stylesheets_dir_name variable. See the above example for reference.
Minify and compress stylesheets for production use
# set the :compass_output to 'compressed' for minified CSS. # Other options include: # + 'expanded' # + 'compact' # + 'compressed' (default) set :compass_output, 'compressed'
Developers can choose what compression level should be used when compiling stylesheets. 'Compressed' is the recommended/default value for maximum compression and optimization for staging or production environments. 'Expanded' is ideal if you're doing development as no compression or optimization is utilized (not suggested for staging or production environments).
# Uploads compiled stylesheets to their matching watched directories for each web server # # Note: This task can be skipped if the `:compass_watched_dirs` variable # is not set or set to `nil` # # see https://github.com/augustash/capistrano-ash/blob/master/lib/ash/base.rb#L447-L486 compass:upload_stylesheets
Why upload stylesheets instead of compiling remotely on the server? The answer is pretty simple, not every server has Ruby or Ruby Gems installed (shocking, I know) and available to the user so remote compiling is kind of a luxury for those of us who work on virtual or private servers the majority of the time. So what's readily available to us that doesn't suck (looking at you FTP and all the FTP clients) and can be easily installed on every developer's machine?
- ruby gems (hint:
gem install compassif you haven't already)
- secure copy
man scpin your terminal window to read the documentation)
- secure FTP
sftp(still FTP but at least it's secure and can be done in the terminal. Read the documentation via
man sftpin your terminal)
rsync(my favorite utility. run
man rsyncin your terminal window to read the documentation)
Compiling locally and uploading the compiled stylesheets (via
scp in our case) means developers don't have to mess around with getting ruby or ruby gems installed onto a remote server and can instead use what they already have on their local machines. This works regardless if the remote server is a shared hosting environment or a virtual/private server.
Automation is the greatest thing since automatically sliced bread
# compile the Sass stylesheets for each of the `:compass_watched_dirs` # # Note: This task will attempt to determine where the bin executable version # of compass is on your system. If it cannot find it, you may need to install # compass # # gem install compass # # OR manually define the path to your compass bin # # set :compass_bin, "my/custom/path/to/my/compass/bin" # # Note: This task can be skipped if the `:compass_watched_dirs` variable # is not set or set to `nil` OR if the `:skip_compass_compile` variable is `true` # # see https://github.com/augustash/capistrano-ash/blob/master/lib/ash/magento.rb#L24 compass:compile
Automating uploading of stylesheets
Refer to the Uploading Stylesheets section above
Automating fixing of permissions
Nothing like the good old
ash.fixperms task to cure what ails your file system from the dirty, dirty wrong doings that slutty folders or files may invite in (worse than Ouija boards I tell ya).
Bringing it all together
Each recipe has the
compass task "baked" in to the task chain so it will run as long as
:compass_watched_dirs is set.
Refer to the
compass:default task to start going down the rabit hole (see the code).
Did I mention it's optional?
If you don't use compass/sass for your project, simply leave
:compass_watched_dirs set to
nil (default value). And by
nil I don't mean an empty string
null — I mean