Development environment instructions.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

A modern Front End development environment

This is a development manual for a digital agency called Dude (Digitoimisto Dude Oy), check out the company website where @ronilaukkarinen is the head of technical development at the moment. Dude is using plenty of tools, apps, modules, frameworks which together are called "stack". Dudestack-instructions contains information about these tools and instructions on how to set up a similar stack.

This wiki and instructions exist only because Dude's envinroment setup is growing in a fast pace and there's simply too many repositories to consider when building the stack from scratch.

The instructions assume that you don't have anything pre-installed. If you have something installed, please just skip the step. Scroll down to Installation.

We hope you enjoy!

Table of contents

  1. Setting up
  2. Requirements
  3. Install requirements
  4. Install macOS LEMP (preferred)
  5. Install Vagrant (optional)
  6. Install dudestack
  7. Install devtools (optional)
  8. Install starter theme
  9. How to generate local site specific HTTPS certificates (optional)
  10. Building blocks for SCSS, jQuery, PHP
    1. For building
    2. For developing and designing
      1. Layout
      2. Typography
      3. Effects
      4. WordPress-themes
      5. Freebies
      6. Inspiration and useful parts
    3. For testing and debugging
    4. Other apps and tools included in daily workflow

Setting up

These will be installed if you follow the instructions:

Install requirements

  1. Install latest version of XCode to get necessary utils. Apple's XCode development software is used to build Mac and iOS apps, but it also includes the tools you need to compile software for use on your Mac. XCode is free and you can also find it in the App Store.
  2. Install Xcode Command Line Tools by running 'xcode-select --install'
  3. Install Homebrew. Open Terminal and run ruby -e "$(curl -fsSL" to download latest version of Homebrew
  4. Run brew install caskroom/cask/brew-cask to get Homebrew Cask
  5. Install latest version of rvm with curl -L | bash -s stable --auto-dotfiles --autolibs=enable --rails to get ruby working
  6. Install latest version of Git with brew install git
  7. Install latest version of Composer with curl -sS | php && sudo mv composer.phar /usr/local/bin/composer && sudo chmod +x /usr/local/bin/composer

Install macOS LEMP (preferred)

Follow the Installation instructions of native LEMP components on Mac

Install Vagrant (optional)

Follow the Installation instructions of our Vagrant box.

Install dudestack

  1. Clone dudestack to your Projects directory with cd ~/Projects && git clone
  2. Run cd ~/Projects/dudestack && sh bin/ and complete the setup process
  3. Run createproject and wait the script to run through. Note: It's intended that every project name is one word, written in lowercase.

Install devtools (optional)

If you want to use your own Gulpfile, Gruntfile, bower, etc, in this point you are practically done. Congratulations! However, if you want to use dudestack-packages, please continue reading.

  1. Go to your project directory by cd ~/Project/projectname and clone devpackages with git clone . (note the dot in the end of a command, we want these to the same directory)
  2. Edit PROJECTNAME (project folder name) and THEMENAME (your theme folder name in content/themes/x) to match your WordPress project and theme name sin gulpfile.js and package.json.
  3. Install Node.js with brew install node
  4. Install npm updates checker npm-check-updates with sudo npm install -g npm-check-updates
  5. Check updates for npm modules by running npm-check-updates -u (still in the Project directory, /Users/yourusername/Projects/yourproject. You can check where you are by pwd)
  6. Install npm package updates by npm install and update them by npm update
  7. Run gulp watch. A new browser window should open and you can start coding your WordPress theme.
  8. If you want to create a landing page instead, go to Project dir with cd ~/Projects, clone modern-html5-boilerplate with git clone, rename folder to your project, edit gulpfile.js and start coding

Install starter theme

Follow the Installation instructions in air theme repository.

How to generate local site specific HTTPS certificates (optional)

  1. First, create a ~/Certificates directory to your $HOME.

  2. cd ~/Certificates, then generate a key (replace PROJECTNAME with your actual project name that you defined in createscript process:

openssl genrsa -des3 -passout pass:x -out PROJECTNAME.pass.key 2048 && openssl rsa -passin pass:x -in PROJECTNAME.pass.key -out PROJECTNAME.test.key && rm PROJECTNAME.pass.key
  1. Then, generate a certificate based on that key:
openssl req \
    -key PROJECTNAME.test.key \
    -x509 \
    -nodes \
    -new \
    -out PROJECTNAME.test.crt \
    -subj /CN=PROJECTNAME \
    -reqexts SAN \
    -extensions SAN \
    -config <(cat /System/Library/OpenSSL/openssl.cnf \
        <(printf '[SAN]\nsubjectAltName=DNS:PROJECTNAME')) \
    -sha256 \
    -days 3650
  1. Then create one for localhost (BrowserSync):
openssl genrsa -des3 -passout pass:x -out localhost.pass.key 2048 && openssl rsa -passin pass:x -in localhost.pass.key -out localhost.key && rm localhost.pass.key
openssl req \
    -key localhost.key \
    -x509 \
    -nodes \
    -new \
    -out localhost.crt \
    -subj /CN=localhost \
    -reqexts SAN \
    -extensions SAN \
    -config <(cat /System/Library/OpenSSL/openssl.cnf \
        <(printf '[SAN]\nsubjectAltName=DNS:localhost')) \
    -sha256 \
    -days 3650
  1. Open Keychain Access app from macOS Launchpad. Click Certificates, then File > Import Items..., navigate to Certificates directory and select your crt file. Double click added Self-signed root certificate, select Trust and choose Always Trust in When using this certificate: selection. Make sure all dropdowns are Always Trust. Close box, add your password and press Update Settings button. Do the same for localhost.

  2. Change browserSync part of gulpfile.js to match this (with your own username of course):

  browserSync.init(files, {
    proxy: "https://PROJECTNAME.test",
    notify: true,
    browser: "Chromium",
    https: {
      key: "/Users/rolle/Certificates/localhost.key",
      cert: "/Users/rolle/Certificates/localhost.crt"

Please note: You don't need to do localhost after first time, once is enough.

  1. Change your siteurl and homeurl protocols to https in your .env file:
  1. Update your marlin-vagrant or macos-lemp-setup vhost like this:
server {
    listen 443 ssl http2;
    root /var/www/PROJECTNAME;
    index index.php;    
    server_name PROJECTNAME.test;

    include php7.conf;
    include global/wordpress.conf;

    ssl_certificate /Users/rolle/Certificates/PROJECTNAME.test.crt;
    ssl_certificate_key /Users/rolle/Certificates/PROJECTNAME.test.key;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;
    ssl_session_timeout 1d;
    ssl_session_cache shared:SSL:50m;
    ssl_stapling_verify on;
    add_header Strict-Transport-Security max-age=15768000;

server {
    listen 80;
    server_name PROJECTNAME.test;
    return 301 https://$host$request_uri;
  1. Run sudo nginx -t to test nginx settings (on macos-lemp-setup) and restart your nginx service.

Building blocks for SCSS, jQuery, PHP

You will need a WordPress theme, User Interface or website base, so I have collected some useful bits and pieces below.

For building

  • BitBucket - Bitbucket is a free code DVCS hosting site for Git and Mercurial. Manage your development with a hosted wiki, issue tracker and source code.
  • Homebrew - The missing package manager for macOS
  • Homebrew Cask - Homebrew Cask extends Homebrew and brings its elegance, simplicity, and speed to macOS applications and large binaries alike.
  • RVM - RVM is a command-line tool which allows you to easily install, manage, and work with multiple ruby environments from interpreters to sets of gems.
  • Node.js - Node.js® is a platform built on Chrome's JavaScript runtime for easily building fast, scalable network applications.
  • npm - A package manager for node/browsers/gulp/etc.
  • Vagrant - Create and configure lightweight, reproducible, and portable development environments.
  • Vagrant Manager - Manage your vagrant machines in one place with Vagrant Manager for macOS.
  • Gulp - Automate and enhance your workflow (my gulpfile.js can be found in devpackages)
  • BrowserSync - Time-saving synchronised browser testing. (included in Gulp like in many other awesome tasks, check out my devpackages)
  • Bower - A package manager for the web (to install and update CSS/Javascript packages and their dependencies, see my devpackages)
  • Composer - Dependency Manager for PHP
  • WP-CLI - A command line interface for WordPress
  • Google Chrome Canary - Google Chrome Canary has the newest of the new Chrome features.
  • Sublime Text 3 - Sublime Text is a sophisticated text editor for code, markup and prose. (also check out current sublime-settings)
  • Atom - The hackable text editor by GitHub. Check out atom-settings

For developing and designing

  • Jeet Grid System - Smart CSS preprocessor grids
  • Normalize.scss - A modern, HTML5-ready alternative to CSS resets
  • Vide - Easy as hell jQuery plugin for video backgrounds
  • jQuery.equalHeights - Simple equal heights jQuery plugin
  • Packery - Packery makes your crazy & clever layout a real thing.
  • macy.js - A lightweight dependency-free JavaScript library designed to sort items vertically into columns by finding an optimum layout with a minimum height.
  • Magnific Popup - Magnific Popup is a responsive lightbox & dialog script with focus on performance and providing best experience for user with any device
  • fancyBox - Fancy jQuery Lightbox Alternative
  • Typographic - Easy SCSS or Stylus responsive typography with vertical rhythm, modular scale, font stacks, and more
  • Sass Boilerplate's fontFace - Easy include a webfont
  • knife - Nail vertical rhythm, modular scale, and REMs like a boss with this simple set of SASS/SCSS variables, functions and mixins.
  • Sassy-Gridlover - Super easy to use Sass mixins to establish a typographic system with modular scale and vertical rhythm. (alternative)
  • Sassline - Set text on the web to a baseline grid with Sass & rems.
  • mo.js - Motion graphics toolbelt for the web
  • Animate.css - A cross-browser library of CSS animations. As easy to use as an easy thing.
  • WOW.js - Reveal Animations When Scrolling
  • Slick - The last carousel you'll ever need
  • skrollr - Parallax scrolling for the masses
  • waypoints - Waypoints is the easiest way to trigger a function when you scroll to an element.
  • saffron - A simple Sass mixin library for animations and transitions
  • Air-light - A minimalist WordPress theme starting point
Inspiration and useful parts

Testing and debugging

  • caniuse-cmd - Caniuse command line tool
  • Google PageSpeed Insights - The PageSpeed tools analyze and optimize your site following web best practices.
  • GTMetrix - GTmetrix gives you insight on how well your site loads and provides actionable recommendations on how to optimize it.
  • alix - Alix is a browser extension for a11y.css. It allows you to lint your HTML for Accessibility issues simply by applying a stylesheet that makes use of advanced CSS selectors.
  • tota11y - An accessibility (a11y) visualization toolkit
  • WAVE - Web accessibility evaluation tool

Other apps and tools included in daily workflow

Please let me know if you have suggestions for new/better apps/modules/plugins...

  • PixelSnap - The fastest way to measure everything on screen.
  • ColorSnapper - The missing color picker for Mac
  • KeepingYouAwake - Don't let your Mac fall asleep
  • Amphetamine - With Amphetamine, you can effortlessly override your energy saver settings and keep your Mac awake.
  • Trello - Trello is the free, flexible, and visual way to organize anything with anyone.
  • Todoist - Todoist is the best online task management app and to-do list.
  • f.lux - Is your computer keeping you up late? f.lux is free software that warms up your computer display at night, to match your indoor lighting.
  • ImageOptim - better Save For Web
  • Moom - Move and zoom windows
  • LittleIpsum - The best Latin text generator for macOS. Incredibly quick and lightweight. And it’s completely free!