Drupal 8 website setup using Composer template

This post is about:

  • Drupal 8.0.0+

This post describes setting up Drupal 8 website from scratch using Composer template for Drupal projects created by webflo and other contributors, adding contributed modules, and moving the website to a production environment.

Before start: make sure you have Composer installed.

1. In the web root of your environment (e.g. /var/www) run:

composer create-project drupal-composer/drupal-project:~8.0 SOMEFOLDERNAME --stability dev --no-interaction

The template will create folder structure for your project, download Drupal 8, download and install (locally) Drush and Drupal Console.

It'll take some time to run. In the end you will see:

Writing lock file
Generating autoload files
> sh ./scripts/composer/post-install.sh

The following folder structure will be created inside of 'SOMEFOLDERNAME':

Folder structure using Composer template for Drupal projects

Drupal 8 files are located in /web.

Drush and Drupal Console will be installed as well.

2. Install Drupal by running install.php script.

3. Change permissions for sites/default folder, settings.php, and services.yml files.

chmod 555 sites/default
chmod 444 sites/default/settings.php
chmod 444 sites/default/services.yml

4. Create temporary folder.

This can be created as sites/default/files/tmp, or, alternatively, one level above root '../tmp'. Make sure this is not some obscure folder on the local server, otherwise your site will explode when moved to production environment.

In the Drupal admin interface go to /web/admin/config/media/file-system and specify appropriate path for 'Temporarily directory'.

5. Set up settings.local.php file, if you want to have different database credentials or environment settings for your local and production environments.

  • Open /sites folder, make a copy of example.settings.local.php
  • Comment out any settings you don't need
  • Copy database settings from sites/default/settings.php and modify as needed for your local setup
  • Save this newly created file as settings.local.php in sites/default folder (same location as settings.php file)
  • Edit settings.php, un-comment the following, move to the bottom of the file, and save:
 if (file_exists(__DIR__ . '/settings.local.php')) {
   include __DIR__ . '/settings.local.php';
  • Add settings.local.php to .gitignore

6. Create git repository in the root of your project (one level above /web)

git init  # will initiate a git repo
git status  # will show you that a repo has been created and a list of untracked files
git add .  # will add all files in the folder to git

Make sure that web/sites/default/services.yml and web/sites/default/settings.php files are added, while web/sites/default/settings.local.php is not.

If all looks good, make an initial commit:

git commit -am “Initial commit”

Check git status, you should see:

On branch master
nothing to commit, working directory clean

7. Add contrib modules to your site.

Using Admin Toolbar as an example. From the project root (one level above /web, which is Drupal root) run:

composer require drupal/admin_toolbar 8.1.*@dev

You'll see something like:

=> composer require drupal/admin_toolbar 8.1.*@dev
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
  - Installing drupal/admin_toolbar (8.1.11)
    Loading from cache

Writing lock file
Generating autoload files

Composer will create a new folder /web/modules/contrib and place admin_toolbar module folder inside.

Now you can enable the module either via 'drush en' or by going to [local-site-url]/web/admin/modules in your browser.

8. Commit adding the module to your git repo:

git status
	modified:   composer.json
	modified:   composer.lock

git commit -am "Adding admin_toolbar"

9. Repeat steps 7 and 8 to add other modules you need.


Move your site to a different environment (e.g. production)

1. Create an external Git repo. Bitbucket is a good option, as it gives you unlimited private repos on their free plan.

2. Push the code from your local repo to the new external one.

3. Export your database locally.

4. On production: create database with the same name as you specified in settings.php. Import database export from step 3 there.

5. On production: checkout your external git repo.

6. On production: cd into your project root directory (one level above /web) and run:

composer install

The installation script will run and download Drupal core, all the contrib modules, and their dependencies.

7. Visit your Drupal site in the browser.

8. If anything is exploding, don't panic and clear cache. Run: 'drush cr' from the /web directory (Drupal root).

9. Various things to check:

  • Make sure tmp directory exists and is writable by Apache user (typically the user name is www-data):
chown www-data:www-data tmp
chmod 775 tmp
  • Make sure the following things have proper permissions:
chmod 555 sites/default
chmod 444 sites/default/settings.php
chmod 444 sites/default/services.yml
  • Make sure the files directory is owned by Apache user with write permissions for it:
chown www-data:www-data files
  • Check status report at /web/admin/reports/status.


For more information (and thanks to authors of those, helped me to figure this out):


Further posts in the series: