Compiling and deploying Sass stylesheets

grafikchaos edited this page Feb 19, 2013 · 1 revision

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.

If :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 :compass_watched_dirs (i.e., 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).

Uploading Stylesheets

# 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: compass or gem install compass if you haven't already)
  • secure copy scp (hint: run man scp in 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 sftp in your terminal)
  • rsync (my favorite utility. run man rsync in 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

Automating compiling

# 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

Refer to the compass:compile task in the code

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 "" or nullI mean nil