Implementing Bootstrap 3.X from Scratch

Generally, I start a website project with an existing template that I then adapt and modify to suit the project’s needs. This weekend, I decided to start a new project from scratch so that I could sharpen both my Bootstrap and DevOps skills.

Rather than begin with a blank screen, I took advantage of several ‘state-of-the-craft’ frameworks and tools to help me along more quickly:

This tutorial describes how to launch a new website project based on HTML5BoilerPlate and Bootstrap 3 with LESS. It will also touch on installing and using Node.js and Grunt.js – if these are already installed on your system, you can skip steps two and three.


Table of Contents:

  1. Starting Assumptions
  2. Install Node.js
  3. Install the Grunt CLI
  4. Set Up the Project Folder
  5. Install Bootstrap
  6. Test the Bootstrap Build Process
  7. Add .htaccess to the Fonts Folder
  8. Include the CSS & JS Files
  9. Add Content & Test
  10. Conclusion

1: Starting Assumptions

Before starting, be sure the following is true:

  • You are comfortable workingHTML, CSS, and JS
  • You are familiar with command-line basics *
  • Your system uses an Apache server

* Command-line instructions are shown for Linux Ubuntu 16.04. You may need to make adjustments if you are using a different OS, or if you prefer to use an IDE or GUI-based text-editor (i.e SublimeText).

 


2: Install Node.js

First thing is to make sure node.js is installed. Node.js includes a package manager that will be used to install both Grunt and Bootstrap, namely npm.

At the command line, navigate to the head of the root directory, then enter the following commands: *

curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y nodejs

This will install the current stable version of node.js.

* Note these commands will work for Ubuntu 14.04 and 16.04. If you are on a different base, check out the node.js website for the correct commands.


3: Install the Grunt CLI

First, make sure your version of npm is up-to-date. At the command line, navigate to the head of the system’s root directory and run:

sudo npm update -g npm

Next, install Grunt’s command line interface globally. From the same location as above, enter the following command:

sudo npm install -g grunt-cli

This will put the grunt command in the system path, allowing it to be run from any directory.

If you run into any trouble with this or just want to know more, check out Grunt’s ‘getting started’ guide.


4: Set Up the Project Folder

Rather than starting from zero, we’ll use HTML5 Boiler Plate as a starting point.

Go to H5BP’s GitHub page, and download and unzip the source file package. Open the extracted folder and navigate into the dist subfolder. Copy the contents of this subfolder and paste them into the root folder for your project.

Your project folder should now look something like this:

Open and review the .htaccess file. This file contains code designed to maximize your site’s performance. Depending on your project’s hosting setup, some or all of what this file contains may not be needed.

If you’re not comfortable making changes, or if you don’t have permission to edit the server files, leave the .htaccess file as-is. It will make the server work just a bit harder, but not so much that you’ll notice under most circumstances.


5: Install Bootstrap

This is where the power of node.js shows it face. Navigate to the project’s root directory and type:

npm install bootstrap@3

This will create a directory named node_modules and then install Bootstrap in a subdirectory named /bootstrap.

Now navigate into the /bootstrap folder and type:

npm install

This tells npm to open the package.json file that was installed as part of Bootstrap, and automatically install and update any dependencies that are listed.


6. Test the Bootstrap Build Process

At this stage, the Bootstrap code has been installed. We should now be able to make sure the Bootstrap build processes are working properly.

This is where Grunt starts to show its power. Out of the box, Bootstrap makes the following grunt commands available:

  • grunt dist (Just compile CSS and JavaScript)

… Regenerates the /dist/ directory with compiled and minified CSS and JavaScript files. As a Bootstrap user, this is normally the command you want.

  • grunt watch (Watch)

… Watches the Less source files and automatically recompiles them to CSS whenever you save a change.

  • grunt test (Run tests)

… Runs JSHint and runs the QUnit tests headlessly in PhantomJS.

  • grunt docs (Build & test the docs assets)

… Builds and tests CSS, JavaScript, and other assets which are used when running the documentation locally via bundle exec jekyll serve.

  • grunt (Build absolutely everything and run tests)

… Compiles and minifies CSS and JavaScript, builds the documentation website, runs the HTML5 validator against the docs, regenerates the Customizer assets, and more. Usually only necessary if you’re hacking on Bootstrap itself.

Not all of these commands will work out-of-the-gate – some will require extra packages, etc., to be installed. However, grunt dist and grunt watch – the two most important commands – work just fine.

The grunt dist command takes care of compiling, compressing, and updating the CSS and JS files. The grunt watch command automatically triggers grunt dist whenever it detects changes to the CSS and JS files.

To execute these commands, go to the command line and navigate to ../node_modules/bootstrap, and enter the following:

grunt dist

If all has gone well so far, grunt will run the basic build processes involved in compiling and minifying the project’s LESS, CSS, and JS files.


7: Add .htaccess to the Fonts Folder

Create a new file in your code editor, and add the following lines:

<FilesMatch "\.(ttf|otf|eot|woff|woff2|svg)$">
  <IfModule mod_headers.c>
    Header set Access-Control-Allow-Origin "*"
  </IfModule>
</FilesMatch>

Save the newly created file directly inside the fonts folder naming it .htaccess.

FYI, the .htaccess file stays within the fonts folder, ensuring web fonts work will in all browsers across all hosting and CDN services the project uses.


8: Include the CSS & JS Files

Open the project’s index.html file, and make the following change in the <head> section:

<!-- REMOVE THIS
<link rel="stylesheet" href="css/normalize.css">
<link rel="stylesheet" href="css/main.css">
-->
<!-- REPLACE WITH THIS -->
<link rel="stylesheet" href="node_modules/bootstrap/dist/css/bootstrap.css">
<link rel="stylesheet" href="node_modules/bootstrap/dist/css/bootstrap-theme.css">

This will instruct the index page to load the new Bootstrap CSS files instead of the defaults that come with H5BP.

Now go to the bottom of index.html to just before the Google Analytics script block, and make the following changes:

<script src="js/plugins.js"></script>
<!-- REMOVE THIS
<script src="js/main.js"></script>
-->
<!-- ADD THIS -->
<script src="node_modules/bootstrap/dist/js/bootstrap.min.js"></script>

Save the file, but don’t close it just yet. We’ll be adding more to this page in the next step.


9: Add Content & Test

While we’re far from done, the basic setup can now be tested to make sure everything was properly installed and included. In the body section of index.html, add this simple markup:

Push index.html to the server and open the page in a browser. If all has gone well, you should now see a styled page with a top menu bar, like so:

Shrink the browser to the size of a smartphone. You should now see a button that exposes a drop-down version of the main menu when clicked, like so:

If something has gone wrong, you’ll likely see un-styled content. Go back and keep debugging until it works.


10: Conclusion

At this stage, you should now have a robust, fully-configured – albeit ‘vanilla’ – Bootstrap project ready for development to begin.


Next Steps:

Although everything should be working just fine with this setup, there are still many things that can be done to improve the project’s infrastructure before jumping right into development.

For example:

  • Modify gruntfile.js to save the compressed and minified CSS and JS files to the locations and filenames initially specified in the original H5BP template, allowing for more efficient script and file loading in production
  • Modify the LESS infrastructure to extend (rather than modify) Bootstrap’s original files, allowing for easier upgrades and more efficient development

Addendum:

Avoid using Initializer to do the install – great idea, but the included versions of the various packages are out of date.

Accessing the Boot Screen in Windows 10

I recently needed to install Linux alongside Windows 10, and discovered that accessing the boot screen has become a bit more involved that just punching the F1 key on startup. There are two ways to get there as described by Microsoft.

From the settings screen:

  1. Select the Start button, then choose Settings .
  2. Select Update & security > Recovery.
  3. Under Advanced startup select Restart now.
  4. After your PC restarts to the Choose an option screen, select Troubleshoot > Advanced options > Startup Settings > Restart.
  5. After your PC restarts, select a startup setting by pressing the corresponding number.

From the sign-in screen:

  1. On the sign-in screen, hold the Shift key down while you select Power > Restart (in the lower-right corner of the screen).
  2. After your PC restarts to the Choose an option screen, select Troubleshoot > Advanced options > Startup Settings > Restart.
  3. After your PC restarts, select a startup setting from the list of options by pressing the corresponding number on your keyboard.

Installing & Using Composer on Ubuntu 16.04

When I previously installed Composer on my dev server, I made the mistake of doing so while logged in as root. This caused all sorts of permissions-related problems.

I recently decided it was time to sort this out by re-installing Composer properly. Although this should be a no-brainer, I decided to research best practices all the same. I’m glad that I did.

The best tutorial I could find was from DigitalOcean: https://www.digitalocean.com/community/tutorials/how-to-install-and-use-composer-on-ubuntu-16-04. What I like most about their approach, is that it includes instructions for a security check on the installer file.

I also found a lot of very good guidance on the Sitepoint website:

Updating Ubuntu 16.04

Every once in a while, the OS software should be updated.

When logging in to the terminal, there is often a message stating updates are available. To install these, use the following commands:

sudo apt-get update        # Fetches the list of available updates
sudo apt-get upgrade       # Strictly upgrades the current packages
sudo apt-get dist-upgrade  # Installs updates (new ones)

Once the updates are done, it’s necessary to clean up any old stuff that isn’t used any longer. Use this command:

sudo apt-get autoremove

And finally, it’s necessary to restart the server. The best way to do this is from the console — just shutdown and reboot the machine and you’re good to go.

Remote Access With Sublime Text 3

I want to use Sublime Text 3 directly with my external servers so that I can avoid needing to upload changed files from my desktop using another FTP program. I also want to be able to launch it from the command line.

My first approach was to install ST3 directly on one my servers (T60). While this made it available on the server, it also meant that I needed to be on the server in order to access the app.

I started out at https://opensourceinside.blogspot.ca/2016/02/how-to-install-sublime-text-3-build.html . First, I made sure I was logged in to the server as myself (not as root) and then made sure I was in my home directory. Then I ran the following command to complete the install:

cd && wget https://download.sublimetext.com/sublime-text_build-3103_i386.deb && sudo dpkg -i sublime-text_build-3103_i386.deb

Next, I needed to make it possible to launch the app from the command line. I went here http://askubuntu.com/questions/273034/lauching-sublime-text-from-command-line to find more. I ran this command to to enable this capability:

sudo ln -s /opt/sublime_text/sublime_text /usr/local/bin/subl

Now all I need to do to launch ST3 from the command line is run:

subl

This works beautifully, so long as I’m working directly on the server.

I needed another approach for tunneling in remotely from my desktop machine. The simplest solution was to add the Sublime SFTP package (https://wbond.net/sublime_packages/sftp) to my desktop install.

Once added, I followed the instructions in the package description file to set up the config files. There’s a bit more on using public/private key authorization here at https://wbond.net/sublime_packages/sftp/faq#SSHKeys and at https://wbond.net/sublime_packages/sftp/settings .

Works like a charm now!

Well, almost… When I tried to upload changes to the Cake project via Sublime SFTP, I ran into a permissions error since I was not logged in as root. When installed, Cake sets the default owner & group to root:root.

When I did a chown on the app to set a new owner and group, I caused a bit of havoc. It turns out, after doing the chown, I then needed to run the following commands to update permissions on the tmp and log folders and files:

HTTPDUSER=`ps aux | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\  -f1`
setfacl -R -m u:${HTTPDUSER}:rwx tmp
setfacl -R -d -m u:${HTTPDUSER}:rwx tmp
setfacl -R -m u:${HTTPDUSER}:rwx logs
setfacl -R -d -m u:${HTTPDUSER}:rwx logs

All good again:-)