palantirnet/drupal-skeleton

There is no license information available for the latest version (2.0.0) of this package.

A Drupal 8 project template.

2.0.0 2020-07-08 22:19 UTC

README

This is a template for starting Drupal projects using the composer create-project command.

Quick start

This "quick start" section will show you how to set up a local server accessible at http://example.local with Drupal ready to install.

Preface

You should have the development dependencies installed on your Mac before you begin. These dependencies are not project-specific, and you may have some or all of them already installed. If you don't, find a location with good internet and set aside at least an hour to complete this step.

The development dependencies are:

Once you have your dependencies installed, setting up this skeleton will take at least another hour, depending on your internet connection.

Some of the commands below will prompt you for a response, with the default answer in brackets. For this quick start, hit return to accept each default answer:

Enter a short name for your project [example] :

Steps

  1. Create a new project called "example" based on this template:
composer create-project palantirnet/drupal-skeleton example dev-develop --no-interaction
  1. Go into your new project directory and run the script from palantirnet/the-vagrant to set up a Vagrant environment:
cd example
vendor/bin/the-vagrant-installer
  1. From inside the VM, run the script from palantirnet/the-build to set up the default Drupal variables and install Drupal:
vagrant up
vagrant ssh
vendor/bin/the-build-installer
  1. In your web browser, visit http://example.local -- if you type in this URL, you will need to include the http:// portion for your browser find the site.
  2. Optional: While you are logged into the Vagrant environment, you can run Drush commands like drush status.

Extra Credit

  • Update the README.md based on the contents of README.dist.md
  • Update the project name in the composer.json file, then run composer update --lock
  • Initialize a git repository and commit your work
  • Access your database via phpMyAdmin at http://example.local/phpmyadmin using the username drupal and the password drupal
  • View email sent by your development site at http://example.local:8025
  • View your Solr 4.5 server at http://example.local:8983/solr
  • Note that renaming or moving this example/ directory can break your Vagrant machine

Full Project Setup

Use Drupal 8 instead of Drupal 9

In general, you'll want to start new projects on Drupal 9 (as of June 2020). However, if you need to create a Drupal 8 testing environment, or use modules that aren't yet compatible with Drupal 9, you can still use a version of this skeleton that supports Drupal 8:

composer create-project palantirnet/drupal-skeleton example dev-drupal8 --no-interaction

Create a project with a custom name

Use composer to create a new project based on this skeleton, replacing PROJECTNAME with the short name for your project:

composer create-project palantirnet/drupal-skeleton PROJECTNAME dev-develop --no-interaction

Update your documentation

Update the README:

  • Remove the README.md
  • Rename the README.dist.md to README.md
  • Edit as you like

Project-specific documentation at docs/technical_approach.md

  • Add deployment.md for deployment instructions

Update the LICENSE.txt:

  • Remove or replace this file with the appropriate license for your project. (The existing license applies to the Drupal Skeleton template only.)

Update the composer.json:

  • Change the name from palantirnet/drupal-skeleton to palantirnet/PROJECTNAME
  • Update the description with a brief description of your project.
  • Update the license property based on how your work will be licensed
  • Update the lock file so composer doesn't complain:
  composer update --lock

Run the installers

Go into your new project directory and run the script from palantirnet/the-vagrant to set up a Vagrant environment:

cd PROJECTNAME
vendor/bin/the-vagrant-installer

From inside the VM, run the script from palantirnet/the-build to set up a base Drupal installation:

vagrant up
vagrant ssh
vendor/bin/the-build-installer

Commit your work to git

Initialize a git repository and commit your work to the develop branch:

git init
git checkout -b develop
git commit --allow-empty -m "Initial commit."
git add --all
git commit -m "Add the skeleton."

Create an empty repository on GitHub for your work. Then, push your work up to the repository:

git remote add origin git@github.com:palantirnet/PROJECTNAME.git
git push -u origin develop

Manage your Vagrant VM

  • Start or wake up your Vagrant VM: vagrant up
  • Log in: vagrant ssh
  • Log out (just like you would from any other ssh session): exit
  • Shut down the VM: vagrant halt
  • Check whether your VM is up or not: vagrant status
  • More information about this Vagrant setup is available at palantirnet/the-vagrant
  • See also the official Vagrant documentation

Replace "the-vagrant" with [something else]

If you'd like to use this skeleton with ddev, drupalbox, lando, or anything else, you can:

  1. composer remove --dev palantirnet/the-vagrant
  2. rm Vagrantfile
  3. Install your development environment of choice
  4. Review and update your .the-build/build.yml:
  • Site URI
  • Database credentials
  1. Update your aliases in drush/ if your site URI has changed
  2. Update your project's README

See also: Customizing your environment with the-vagrant

Replace "the-build" with [something else]

If you're allergic to phing and Benadryl isn't helping, you can also remove the-build:

  1. composer remove --dev palantirnet/the-build

  2. rm -r .the-build

  3. rm build.xml

  4. This will remove drush, coder, and phpmd -- if you want those dependencies, you'll need to add them back to your project:

    composer require --dev drush/drush drupal/coder phpmd/phpmd
    
  5. Review your web/sites/default/settings.*.php files (the-build managed these for you)

  6. Install your build tooling of choice... or nothing at all...

  7. Update your project's README

See also: Documentation on using the-build

Install Drupal from the command line

When using drush or phing to manage your Drupal site, you will need to log into the vagrant box (vagrant ssh).

If you've run vendor/bin/the-build-installer from within the VM, Drupal will be installed and the initial config exported to config/sites/default/.

You can use the phing scripts provided by palantirnet/the-build to reinstall the site from config at any time:

vendor/bin/phing install

Or, you can use drush directly:

drush site-install --existing-config

Manage your configuration in code

In Drupal 8 development, all (or most) Drupal configuration should be exported and treated as part of the codebase. On top of this core process, we use the config_installer profile to allow us to use the exported configuration as the basis for a repeatable, automation-friendly build and install process. We also use config_split to manage environment-specific configuration.

  1. Log into Drupal in your browser and do some basic config customizations:
  • Set the site timezone
  • Disable per-user timezones
  • Disable user account creation
  • Remove unnecessary content types
  • Set the admin email address (your VM will trap all emails)
  • Turn the Cron interval down to "never"
  • Uninstall unnecessary modules (e.g. Search, History, Comment)
  1. Export your config:
drush cex -y
  1. You should have a ton of new *.yml files in config/sites/default/. Add them, and this config change, to git:
git add config/
git ci -m "Initial Drupal configuration."
git push
  1. Reinstall your site and verify that your config is ready to go:
vendor/bin/phing install

More information

Copyright 2016 - 2020 Palantir.net, Inc.