imagex/swat

A Robo CLI tool for ImageX Projects in Drupal 8+

4.0.0 2021-05-10 22:45 UTC

README

SWAT is meant to be a helper for projects within ImageX. It provides a docksal setup for use with BLT as well as some templated Bitbucket pipelines and deployment helpers. And it's super wicked awesome.

Requirements

SWAT requires the following to run:

  1. Docksal - https://docksal.io/
  2. Composer - https://getcomposer.org/
  3. PHP 7

NEW PROJECT

New projects can user either Drupal 8 or Drupal 9.

Drupal 9

  1. composer create-project --no-interaction acquia/drupal-recommended-project <project-name>
  2. cd <project-name>
  3. composer require imagex/swat
  4. ./vendor/bin/swat setup
    1. There is possibly some version constraints in modules here requiring customized composer.json
  5. Configure blt.yml specific to project
    1. Add Project Prefix
    2. Add Remote Git repo (Acquia, pantheon, etc)
    3. Add Remote Git user/email (see example below)
    4. Configure profile, etc, etc
  6. ./vendor/bin/swat install

Drupal 8

  1. composer create-project --no-interaction acquia/blt-project <project-name>
  2. cd <project-name>
  3. composer require imagex/swat
  4. ./vendor/bin/swat setup
  5. Configure blt.yml specific to project
    1. Add Project Prefix
    2. Add Remote Git repo (Acquia, pantheon, etc)
    3. Add Remote Git user/email (see example below)
    4. Configure profile, etc, etc
  6. ./vendor/bin/swat install

Pantheon

  1. Perform steps above
  2. Clone pantheon git into another folder
  3. Copy pantheon.upstream.yml from it to your repo root
  4. Copy sites/default/settings.pantheon.php to web/sites/default/settings/pantheon.settings.php

    1. Edit the pantheon settings to set config dir properly (i.e. dirname(DRUPAL_ROOT) . '/config/default')
    2. copy the following to the bottom of web/sites/default/settings.php

       /**
        * Include the Pantheon-specific settings file.
        *
        * N.b. The settings.pantheon.php file makes some changes
        *      that affect all envrionments that this site
        *      exists in.  Always include this file, even in
        *      a local development environment, to insure that
        *      the site settings remain consistent.
        */
       include DRUPAL_ROOT . "/sites/default/settings/pantheon.settings.php";
      
  5. Deploy bitbucket repo to pantheon
  6. Make a local DB Dump (fin db dump > db.sql)
  7. Import it into pantheon
  8. Run another deployment to confirm working with Quicksilver.

BLT Additional Setup

View documentation from BLT: https://github.com/acquia/blt

[Drupal\Core\Installer\Exception\InstallerException] Database settings: Array Add Namespace to local settings: https://github.com/acquia/blt/issues/4271

Example of Git config in blt.yml for remote:

    git:
      default_branch: develop
      remotes:
        cloud: 'fingate@svn-23450.prod.hosting.acquia.com:fingate.git'
      user:
        name: 'Bryan Sharpe'
        email: bryans@imagexmedia.com

Mutagen (Optional - OSX Performance)

You will need to have mutagen installed first.

  1. Follow steps 1-5 above
  2. Copy ./vendor/imagex/swat/config/mutagen.yml to your repo root
  3. Update the commented line to fit your project
  4. Uncomment the line in ./.docksal/docksal-local.env for volumes
  5. Run fin p reset NOTE: This will delete your containers.
  6. Run mutagen project start && mutagen sync monitor, wait until all files are sync'd and cmd+C out
  7. Continue install steps.
Available Commands
  help                 Displays help for a command
  hosting              Setup Hosting for SWAT tasks.
  list                 Lists commands
 bitbucket
  bitbucket:pipelines  Helper for bitbucket pipelines.
 docksal
  docksal:create       Creates a docksal project.
 packages
  packages:init        Install composer dependencies for packages.
  packages:install     Installs modules set in config.
 setup
  setup:existing       Sets up hosting and piplines.
  setup:init           [setup] Setup Hosting, Docksal, Bitbucket, Theme, and Settings.
  setup:install        [install] Installs a new site using BLT.
 theme
  theme:bootstrap      Helper for adding bootstrap assets.
  theme:composer       Adds bootstrap to composer..
  theme:create         Helper for setting up a basic theme.
  theme:setup          Helper for setting up a basic theme.

Existing Projects

For existing projects you can still get hosting pipelines or docksal setup.

  1. composer require imagex/swat
Available Commands

setup:existing

  • This command runs both hosting and pipeline commands.

hosting

  • Setup the defaults for a hosting/deployment.

bitbucket:pipelines

  • Installs a default pipeline based on hosting

docksal:create

  • Creates a new docksal configuration

Throubleshoot

  1. Command pm-enable was not found. Drush was unable to query the database. (when running swat install)

    1. Add the 'namespace' => 'Drupal\\Driver\\Database\\mysql' to $databases['default']['default'] in sites/default/settings/local.settings.php
  2. [Composer\Downloader\TransportException] Resolving timed out after 10000 milliseconds

    1. Try upgrading composer to version 2.
  3. shell-init: error retrieving current directory: getcwd: cannot access parent directories: No such file or directory

    1. Check if CLI container ({project_name}_cli_1) is up.
    2. If it is not running, or you have any other issue, try to reset the container ({project_name} fin project reset cli). Test it by running fin exec node -v
  4. Local PHP modules

    1. If you get any error when running composer create-project... related with missing PHP extensions/modules, try to install those using the command: sudo apt-get install php7.4 libapache2-mod-php7.4 php7.4-common php7.4-gd php7.4-mysql php7.4-curl php7.4-intl php7.4-xsl php7.4-mbstring php7.4-zip php7.4-bcmath php7.4-soap php-xdebug php-imagick. Change the 7.4 for the version of your PHP.