Notebooks - LCM Drupal 8 Scaffold

2.1 Pull down the scaffold

Use Composer to grab the project code.

@ YOUR-PROJECT folder

composer create-project lastcall/drupal-scaffold YOUR-PROJECT-NAME

This command installs a long list of php packages in the YOUR-PROJECT/YOUR-PROJECT-NAME folder . Not just Drupal code but also php packages that are useful for developing a Drupal project (like Drush and Drupal Console...)

In the terminal you'll see the following kind of output...

Loading composer repositories with package information
Installing dependencies (including require-dev) from lock file
  - Installing cweagans/composer-patches (1.6.0)
    Loading from cache
 
Patching is disabled. Skipping.
  - Installing hirak/prestissimo (0.3.5)
    Loading from cache    
...

Installing php modules with composer always ends with a list of suggestions for installing related modules, something like this...

zendframework/zend-feed suggests installing zendframework/zend-cache (Zend\Cache component, for optionally caching feeds between requests)
zendframework/zend-feed suggests installing zendframework/zend-db (Zend\Db component, for use with PubSubHubbub)
zendframework/zend-feed suggests installing zendframework/zend-http (Zend\Http for PubSubHubbub, and optionally for use with Zend\Feed\Reader)
 
...

These suggestions can be ignored, although reading through them might trigger some ideas about how you can extend the functionality of any of the code in the project.

The composer installation end with the nice message:

Generating autoload files

Take a look in your project folder. In the vendor folder you will find the packages Composer has downloaded. Drupal Console is there, and so is Drush...

That's that.

2.2 Install NPM Dependancies

cd into your project folder

cd YOUR-PROJECT-NAME

If you are using NVM to manage which version of NPM you use in a given project (nice idea!) Set it to use the latest stable version:

nvm install stable; nvm use stable;

If you are not using NVM to manage which version of NPM you are using in a project you can install the latest stable version of NPM with:

npm install npm@latest -g

Now install NPM modules:

@ Project Root

npm install

NPM installations almost always begin with some warnings about deprecated modules. As NPM modules depend on other NPM modules in cascading tree of 10,000 dependancies this is inevitable. Ussually you can ignore these warnings.

NPM carries on and installs the Node modules you need to run the build process for your Drupal instance.

Of course Drupal is a PHP application built using some Symfony components (and a whole lot of Drupal specific modules,) so why download a long list of Node Modules?

Most of these modules will be used by Gulp during the build process for your theme.

Aside: If you want to review a great build process based on Gulp, check out Zurb Template for Foundation 6. You see alot of the same Node modules and similar tasks used in the Gulp file for this scaffold and the Zurb Template…

This scaffold uses Foundation 6 for a CSS framework on which to build the theme.

2.3 Install Bower and Composer Dependancies

@ Project Root

gulp install

This will install the Project Bower and Composer Dependancies. When the install is complete, check the bower_components folder. Foundation 6 is installed! Very nice indeed.

2.4 Edit Project Definition Files

Open up your project folder with your favorite editor

@ Project Root

code .

Edit the composer.json, package.json, and bower.json and rename the project as needed.

Just change the name of your project and the description in these three files.

Note that in composer.json they use a / to define a namespace followed by a project name "name": "YOUR-NAMESPACE/YOUR-PROJECT-NAME",

While Bower and NPM use a . to define a namespace followed by a project name "name": "YOUR-NAMESPACE.YOUR-PROJECT-NAME",

2.5 Edit your custom theme name

@ web/themes/custom

Rename the scaffold folder to the name of your choice for your custom theme. Inside your newly renamed custom theme folder use your chosen custom theme name to rename the .js file and the .scss file.

2.6 Commit code to a repo

So, at this point it's a good idea to initiate a git repo and push to github.

Checkout the .gitignore file. It uses sensible defaults. No need to change anything here..

Here's the first big win! No dependancies or third party libraries are bulking up your github repo! Its lean and lightweight.

See your composer.lock file in your github repo. Great. When your team members download the repo they will install exactly the right versions of everything needed to build a clone of the site.

Initialize a new git repository and push work to it as normal

git init && git add . && git commit

Create a repo on github and push to origin...

2.7 Install Docker

Lets make sure everyone on the development team is using exactly the same development environment. That will make for a lot less headache for the dev-ops person.

Docker will create a LAMP stack container to host the Drupal site based on some sensible defaults.

If Docker is not installed you can follow these instructions.

Another very nice option is to install Kitematic which is a GUI app on Mac you can use to install and manage Docker containers. When you install Kitematic it automatically installs and configures Docker - very smooth.

2.8 Edit Docker Config Files

When you run Docker it will spin up a set of containers. There will be one container for each service. Since Drupal is being served we will need a container each for MySQL, Apache, PHP all running on Linux.

These four containers are knitted together using a docker-compose.yml file. When the docker-compose up command is called from the command line Docker looks for the docker-compose.yml file and ingests the configuration found there.

@ docker-compose.yml

First edit the mysql configuration. Docker will use this configuration to create new database, and database user with the correct permissions.

  mysql:
    image: "mysql:5.6"
    volumes:
      - mysql_data:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=root
      - MYSQL_USER=your-database-user
      - MYSQL_PASSWORD=your-database-password
      - MYSQL_DATABASE=your-database-name

Next use the config you set for mysql to set the config for the Drupal instance

  drupal:
    image: "lastcallmedia/php:7.0"
    volumes:
      - .:/var/www/html
    links:
      - mysql
      - redis
    environment:
      - MYSQL_HOST=mysql
      - MYSQL_PASSWORD=your-database-password
      - MYSQL_USER=your-database-user
      - MYSQL_DATABASE=your-database-name
      - REDIS_HOSTNAME=redis
      - SITE_NAME=scaffold
      - DOCKER_ENV=local

When the docker-compose up command is called from the command line you can also pass in additional config files such as docker-compose.debug.yml.

@ docker-compose.debug.yml

version: '2'
 
services:
  varnish:
    ports:
      - "8080:80"
  drupal:
    ports:
      - "8081:80"
  mysql:
    ports:
      - "33306:3306"
#  solr:
#    ports:
#      - "8983:8983"

2.9 Spinning up the Site

From the scaffold docs:

2.9.0.1 Default configuration

To use the standard configuration, just run docker-compose up. This makes the site available behind Varnish at http://localhost/8080/web.

2.9.0.2 Development configuration

The default setup only exposes port 80 from varnish to the outside world (exposed as port 8080 to the host). This is great for production-like environments, but not for development where you may not want a reverse proxy, or you may need to connect directly to MySQL using a tool like Sequel Pro.

The standard docker-compose.yml can be overridden/added to by specifying multiple compose files when bringing the containers online. This project includes a docker-compose.debug.yml file that exposes ports for all of the relevant containers, allowing direct access to them from the host. You can leverage these debug ports by bringing the containers up with this command: docker-compose -f docker-compose.yml -f docker-compose.debug.yml up

When the debug ports are exposed, the following services are available from the host:

Varnish: You can still access the site behind varnish as you would with only the default config at http://localhost:8080/web
Drupal: You can directly access the Drupal site, bypassing the reverse proxy at http://localhost:8081/web
MySQL: You can make a direct connection from the command line using mysql -h 127.0.0.1 --port 33306 -u drupal -pdrupal drupal
Solr: The Solr web ui can be accessed at http://localhost:8983

Now you have a development server set up. All you need to do is install Drupal 8. That's next!

2.10 Install Drupal

To access the Docker container you use the following command

@ project root

docker-compose exec drupal /bin/bash

Now you access to the Container server from the command line with a prompt something like:

root@f95dbae20ec7:/var/www/html#

The Drupal code base is contained in the web directory. So to begin the install we need to cd into that

cd web

From here we use Drupal Console to install the site (or, Drush…) Remember the executables for Drupal Console or Drush are outside the web folder so we go up a level in the driectory structure and into vendor/bin where a bunch of useful executables have been installed

../vendor/bin/drupal site:install

Now Drupal Console will walk you through the installation. All you have to do is fill in the blanks or accept the defaults.

Notice during installation the database name and user are already defined.

 Select language for your Drupal installation [English]:
 > 
 Using "mysql" database with name "your-database-name" and user "your-database-user"

This database and user (and password) were created when Docker set up the container using the config found in docker-compose.yml

After a sucessful installation you will need to clear the cache

../vendor/bin/drupal cr all

2.11 Visit the Site

Varnish: You can still access the site behind varnish as you would with only the default config at http://localhost:8080/web
Drupal: You can directly access the Drupal site, bypassing the reverse proxy at http://localhost:8081/web
MySQL: You can make a direct connection from the command line using mysql -h 127.0.0.1 --port 33306 -u drupal -pdrupal drupal
Solr: The Solr web ui can be accessed at http://localhost:8983

First test multiple installations…

Next… How to develop...

2.12 Quick Review: Access to Docker

From the project root - not the container command prompt...

Starting the application:

docker-compose up -d

Stopping the application:

docker-compose stop

Getting shell access:

docker-compose exec drupal /bin/bash

See Docker Compose for more information.

SMERTH

building with 100% re-cycled electrons.

Previous
Chapter 1 - LCM Drupal 8 Scaffold

SMERTH

LCM Drupal 8 Scaffold

Chapter 2 - Installation

2.1 Pull down the scaffold

2.2 Install NPM Dependancies

2.3 Install Bower and Composer Dependancies

2.4 Edit Project Definition Files

2.5 Edit your custom theme name

2.6 Commit code to a repo

2.7 Install Docker

2.8 Edit Docker Config Files

2.9 Spinning up the Site

2.9.0.1 Default configuration

2.9.0.2 Development configuration

2.10 Install Drupal

2.11 Visit the Site

2.12 Quick Review: Access to Docker

PreviousChapter 1 - LCM Drupal 8 Scaffold

SMERTH

LCM Drupal 8 Scaffold

Chapter 2 - Installation

2.1 Pull down the scaffold

2.2 Install NPM Dependancies

2.3 Install Bower and Composer Dependancies

2.4 Edit Project Definition Files

2.5 Edit your custom theme name

2.6 Commit code to a repo

2.7 Install Docker

2.8 Edit Docker Config Files

2.9 Spinning up the Site

2.9.0.1 Default configuration

2.9.0.2 Development configuration

2.10 Install Drupal

2.11 Visit the Site

2.12 Quick Review: Access to Docker

Previous
Chapter 1 - LCM Drupal 8 Scaffold