How to configure Sass CSS compilation¶

    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

    Note

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

    If we were doing this by hand we might run:

    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.

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

    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.

    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:

    Various other packages need to be installed locally: gulp, autoprefixer,gulp-clean-css, , 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-postcss": "^6.4.0",
    8.     "gulp-sass": "^3.1.0",
    9.     "gulp-sourcemaps": "^2.4.1",
    10.     "gutil": "^1.6.4"
    11.   },
    12.   "devDependencies": {}
    13. }

    In order to process these, you can add:

    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.

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

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

    Note

    The 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 . This file looksfor Sass files in private/sass and compiles them to /static/css.

    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.

    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.

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