README.md

Drupal Starter Kit

This repository is using Amazee's containers.

Requirements

• Git
• Docker

Install and start pygmy

Only on Linux and macOS.

To install pygmy, run gem install pygmy.

This is only needed if you don't already have pygmy installed.

Start pygmy: pygmy up

Create a new project

docker run --rm -it -v $PWD:/app --user $(id -u):$(id -g) tamasd/composer \
 create-project Pronovix/devportal-starterkit \
 -s dev $DEVPORTAL_NAME

This command will create the project files with the containers. It is possible that there will be some error output about missing the gd extension.

These errors can be ignored.

Setup the containers

• Copy docker-compose.unix.yml or docker-compose.windows.yml as docker-compose.override.yml, depending on the host operating system.
• Then run docker-compose up --build -d
• docker-compose run --rm cli sh -c 'composer install'

Setup the site

• Create your settings.local.php file: cp web/sites/example.settings.local.php web/sites/default/settings.local.php
• Create your settings.php file: cp web/sites/default/default.settings.php web/sites/default/settings.php
• Uncomment the inclusion of settings.local.php from the bottom of web/sites/default/settings.php.
• Add the following code to settings.local.php:

If you use MariaDB:

$databases['default']['default'] = [
  'database' => 'drupal',
  'username' => 'drupal',
  'password' => 'drupal',
  'prefix' => '',
  'host' => 'mariadb',
  'port' => '3306',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',
];

If you use Postgres:

$databases['default']['default'] = [
  'database' => 'drupal',
  'username' => 'drupal',
  'password' => 'drupal',
  'prefix' => '',
  'host' => 'postgres',
  'port' => '5432',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\pgsql',
  'driver' => 'pgsql',
];

Add the following snippet as well.

$settings['trusted_host_patterns'] = [
  '^$PROJECT.docker.amazee.io$',
  '^nginx.$PROJECT.docker.amazee.io$',
  '^nginx$',
  '^localhost$',
];

if (!drupal_installation_attempted()) {
  $settings['cache']['default'] = 'cache.backend.redis';
  $settings['redis.connection']['host'] = 'redis';
  $settings['container_yamls'][] = 'modules/contrib/redis/example.services.yml';
  $settings['container_yamls'][] = 'modules/contrib/redis/redis.services.yml';
  $class_loader->addPsr4('Drupal\\redis\\', 'modules/contrib/redis/src');
  $settings['bootstrap_container_definition'] = [
    'parameters' => [],
    'services' => [
      'redis.factory' => [
        'class' => 'Drupal\redis\ClientFactory',
      ],
      'cache.backend.redis' => [
        'class' => 'Drupal\redis\Cache\CacheBackendFactory',
        'arguments' => ['@redis.factory', '@cache_tags_provider.container', '@serialization.phpserialize'],
      ],
      'cache.container' => [
        'class' => '\Drupal\redis\Cache\PhpRedis',
        'factory' => ['@cache.backend.redis', 'get'],
        'arguments' => ['container'],
      ],
      'cache_tags_provider.container' => [
        'class' => 'Drupal\redis\Cache\RedisCacheTagsChecksum',
        'arguments' => ['@redis.factory'],
      ],
      'serialization.phpserialize' => [
        'class' => 'Drupal\Component\Serialization\PhpSerialize',
      ],
    ],
  ];
}

$config_directories['sync'] = '../config/sync';

• After adding this snippet to settings.local.php look up the lagoon project name from docker-compose.yml (e.g. starterkit in starterkit.docker.amazee.io), and replace $PROJECT with it.
• Inside the cli container, run drush si $PROFILE --account-name=admin --account-pass=admin where $PROFILE can be either config_installer (if you already have configuration inside config/sync) or standard (completely new project). Wait until your site gets installed. (This step can be skipped if you would like to import an existing database).

While it is not strictly necessary to enable the redis module, it is recommended to do so.

Import database and public files

Import public files

• Extract the downloaded public files archive: tar -zxvf files.tgz
• Copy the content to the public files location: sudo rsync -av --delete files/ /path/to/project/web/sites/default/files

Import database

• Copy the database to the project's web folder: cp database.sql.gz /path/to/project
• Go to the project directory: cd /path/to/project
• Import the database with drush: docker-compose run --rm cli sh -c 'zcat database.sql.gz | drush sqlc'.

Usual commands

• docker-compose run --rm cli sh

  To run commands inside the container.

• docker-compose up -d

  Starts the containers.

• docker-compose stop

  Shuts down the containers (keeps the state).

• docker-compose down

  Destroys the containers (permanently deletes the state).

Gulp

Copy .env.js as env.js into the project root from the Gulp component and and set your local theme paths.

• Build CSS: docker-compose run --rm gulp sh -c 'npm run gulp'
• Watch SCSS changes: docker-compose run --rm gulp sh -c 'npm run gulp watch'
• Non-minified CSS with source maps: docker-compose run --rm gulp sh -c 'npm run gulp watch -- --debug' (standalone -- is needed to pass an argument to Gulp)

See the the Gulp component for a troubleshooting guide.

Running Mailhog on Windows

As Windows does not support Pygmy (which handles Mailhog on Linux/Mac), Mailhog should be added separately as container (see docker-compose.windows.yml). After installing it with docker-compose up -d you can reach Mailhog by visiting http://localhost:8025/ in your browser.

Debugging

Fixing xdebug on Linux

Open docker-compose.override.yml and follow the instructions in the cli and php sections.

Running tests (optional)

docker-compose -f docker-compose.yml \
  -f docker-compose.tests.yml -f docker-compose.override.yml \
  run --rm tests