How to configure Sass CSS compilation¶

Sass is a popular CSS extension language, favoured by many frontenddevelopers.

This document explains how to implement Sass compilation in a Divio Cloud project. Although thisguide specifically deals with Sass, many of the principles it involves can be applied to othersystems.

In this example we will install, set up and run:

  • Node, the server-side JavaScript application framework
  • npm, the Node Package Manager
  • gulp, to build the Sass CSS

Note

Note that this document assumes you are working with a project that does not already haveNode components set up and activated.

What we want to do¶

If we were doing this by hand we might run:

  1. # Activate Node Version Manager using nvm.sh (installed by default). The directory
  2. # $NVM_DIR is set as an environment variable by the base project:
  3. source $NVM_DIR/nvm.sh
  4. nvm install 6.10.1
  5. nvm alias default 6.10.1  # set a default Node version to be used in any new shell
  6. nvm use default  # use the default Node version now
  7. npm install -g [[email protected]](http://docs.divio.com/cdn-cgi/l/email-protection)  # ensure the correct version of NPM is installed
  8. npm install -g [[email protected]](http://docs.divio.com/cdn-cgi/l/email-protection)
  9. export NODE_PATH=$NVM_DIR/versions/node/v6.10.1/lib/node_modules  # set NODE_PATH as an environment variable
  10. export PATH=$NVM_DIR/versions/node/v6.10.1/bin:$PATH  # Add the node directory to PATH
  11. # Install all required packages for building Sass (locally):
  12. npm install [[email protected]](http://docs.divio.com/cdn-cgi/l/email-protection) [[email protected]](http://docs.divio.com/cdn-cgi/l/email-protection) [[email protected]](http://docs.divio.com/cdn-cgi/l/email-protection) [[email protected]](http://docs.divio.com/cdn-cgi/l/email-protection) [[email protected]](http://docs.divio.com/cdn-cgi/l/email-protection) [[email protected]](http://docs.divio.com/cdn-cgi/l/email-protection) [[email protected]](http://docs.divio.com/cdn-cgi/l/email-protection)
  13. gulp watch  # Start watching the files specified in our gulfile.js to build the CSS

However, we can use Docker to automate this for us, and also use to build some more abstractioninto the process, making it easier to maintain.

Building this into the Dockerfile¶

See the Divio Cloud Dockerfile reference for more information onhow our Dockerfile works.

Set up the Node environment¶

Above, we specified some version numbers for the Node environment, and we can export them hereas environment variables.

In your project’s Dockerfile, after the # <DOCKER_FROM>[…]# </DOCKER_FROM> section:

  1. ENV NODE_VERSION=6.10.1 NPM_VERSION=5.8.0

Using environment variables like this for version numbers allows them to be specified just once,and re-used wherever required.

Other commands can be collected into an installation script file. This will use theNODE_VERSION and NPM_VERSION variables we set above:

  1. #!/bin/bash
  2.  
  3. # Exit immediately in case of error
  4. set -e
  5.  
  6. source $NVM_DIR/nvm.sh
  7. nvm install $NODE_VERSION
  8. nvm alias default $NODE_VERSION
  9. nvm use default
  10.  
  11. npm install -g [[email protected]](http://docs.divio.com/cdn-cgi/l/email-protection)"$NPM_VERSION"
  12. npm install -g [[email protected]](http://docs.divio.com/cdn-cgi/l/email-protection)

The file can be added to the project repository at scripts/install.sh.

Using a separate bash script for the installation commands allows us to maintain a cleanerDockerfile, and manage the installation of frontend components separately from other concerns.

Back in the Dockerfile, we need to copy scripts directory to the container, and then executethe file:

  1. ADD scripts /scripts
  2.  
  3. RUN bash scripts/install.sh

and add the Node components to the appropriate paths:

  1. ENV NODE_PATH=$NVM_DIR/versions/node/v$NODE_VERSION/lib/node_modules \
  2.     PATH=$NVM_DIR/versions/node/v$NODE_VERSION/bin:$PATH

Install other Node packages¶

Various other packages need to be installed locally: gulp, autoprefixer,gulp-clean-css, gulp-postcss, gulp-sass, gulp-sourcemaps, gutil.

These should be added to a package.json in the root of the project:

  1. {
  2.   "name": "package",
  3.   "private": true,
  4.   "dependencies": {
  5.     "autoprefixer": "^6.7.7",
  6.     "gulp": "^3.9.1",
  7.     "gulp-clean-css": "^3.0.4",
  8.     "gulp-postcss": "^6.4.0",
  9.     "gulp-sass": "^3.1.0",
  10.     "gulp-sourcemaps": "^2.4.1",
  11.     "gutil": "^1.6.4"
  12.   },
  13.   "devDependencies": {}
  14. }

In order to process these, you can add:

  1. # <NPM>
  2. # package.json is put into / so that mounting /app for local
  3. # development does not require re-running npm install
  4. ENV PATH=/node_modules/.bin:$PATH
  5. COPY package.json /
  6. RUN (cd / && npm install --production && rm -rf /tmp/*)
  7. # </NPM>

Note

It is strongly recommended to place these lines inside the # <NPM>[…]# </NPM> commentsthat exist by default in every Divio Cloud Dockerfile. This is because the Divio CloudControl Panel will automatically fill this section (if it exists) with appropriate commandswhen it discovers package.json in the project.

Run compilation of CSS at deployment time¶

The final part of the task is to execute gulp build to compile the CSS.

Towards the end of the Dockerfile, inside the # <GULP>[…]# </GULP> section, add:

  1. # <GULP>
  2. ENV GULP_MODE=production
  3. RUN gulp build
  4. # </GULP>

Note

The # <GULP>[…]# </GULP> section exists in the Dockerfile by default. On deployment,the Divio Cloud Control Panel will automatically fill this section (if it exists) withappropriate commands when it discovers gulpfile.js in the project.

You will need an appropriate gulpfile.js at the root of the project too. It is beyond the scopeof this document to describe how to create a gulpfile. For reference however, you may use thefile provided in our own django CMS Boilerplate Sass. This file looksfor Sass files in private/sass and compiles them to /static/css.

Building the updated project¶

Run docker-compose build web (locally) to test the changes, or deploy them to the Test server.

In either case, the project will be started up as before, this time with compiled CSS files.

You can start the project locally with divio project up as usual. Running docker-compose run
—rm web gulp build will start a watcher that executes compilation instantly whenever a Sass filein private/sass is changed.

Further frontend development¶

This is just an example of a particular case. It’s possible to set up very extensive andsophisticated components and processes for your project’s frontend. Our django CMS BoilerplateWebpack is an example.

Though it’s beyond the scope of this documentation to describe how to do this in detail for everycase, the basic principles are the same as in this example. If it’s possible to set up, it’spossible to automate the set-up of your project’s frontend components using Docker with consistentand reliable results.

Using Boilerplates for quicker project creation¶

If you typically use the same particular frontend set-up for many sites, you should considerpackacking it up as a Boilerplate that can be used at project creationtime. See Create a custom Boilerplate in the tutorial section.

原文: http://docs.divio.com/en/latest/how-to/configure-sass.html