Docksal documentation

[shelane]

Changes proposed:

(What are you proposing we change?)

• Adding documentation for the Docksal environment
• Fixing links for alternative environment tips
• Making resource links clickable for ACSF setup page

At the request of @mikemadison13, I put together this documentation page on using BLT in the Docksal environment. I had a little help from @lpeabody in the direction of what should be included in this page. This PR is for 10.0.x, but should be committed to 9.2.x as well.

@mikemadison13 This addresses Les's suggestion as well with an additional comment on setup strategy. BLT should really have more extensive documentation on that as it specific to BLT and not an environment. I rerolled this to 10.0.x since the DDEV docs were included and there would have been a merge conflict with the change to the page with the list of environment tips.

[mikemadison13]

@shelane @lpeabody think the new docs help there. however, i'm still confused, why not just use blt sync if you want to sync and blt setup if you want a clean install? significantly simplifies the command structure. am i overlooking something that blt setup -D setup.strategy=sync does that blt sync does not?

[lpeabody]

@mikemadison13 In 99.9999% of cases there is probably going to be no functional difference between the two of those individual commands. It might be a philosophical question: manually running commands to do different things, or, running a smaller set of commands whose behavior is influenced by configuration. BLT has an extremely strong configuration model, and so it benefits us to leverage that and integrate it with Docksal's robust custom command architecture.

I'll provide some use cases:

Developing and launching a new site
You've been building a profile and testing the site installation process by running fin blt setup. This installs the site. Once the site has launched, you now want the development workflow to synchronize with the remote before starting new work. You update sites/default/blt.yml to reflect the following:

setup:
  strategy: sync
drush:
  aliases:
    remote: group.siteid

You make this change once, it is shared with everyone, and everyone continues to run the same, single command, fin blt setup. Instead of the site installing, the site now synchronizes for everyone.

Docksal-enabled CI environment
I want to continuously verify that my profile installs successfully and existing sites also synchronize correctly. I have two different environment-specific blt.yml files in my default site directory (install.blt.yml and sync.blt.yml). Each of those contain different behat/setup configuration for installing/syncing sites and then running different sets of Behat tests on each. I have a Docksal command fin test-environment which accepts an argument meant to be the environment indicator. That command in turn runs fin blt setup --environment=$1 && fin blt tests --environment=$1, which will setup my site according to configuration as well as run tests against that site according to the same set of configuration.

Finalizing thoughts
The point is, instead of sending an @everyone notification to your developers in Slack to say "as of this commit please start using fin blt sync instead of fin blt drupal:install, you standardize everyone on just running fin blt setup and change the project's configuration to perform a new site setup differently. You can then rope this into Docksal commands like I did above for implementing higher level project operations, such as testing site setups in different environment scenarios like above.

If we're going to be providing documentation on how to best integrate BLT with Docksal, we should be providing some level of philosophical guidance around normalizing your project's command architecture since that is one of the biggest benefits of using Docksal.

EDIT: Just to be clear, I am not saying "this is the way you need to use Docksal with BLT". It is very much open to interpretation and experimentation, that's what makes our jobs so fun :) This is my take on how Docksal and BLT can be integrated in a symbiotic way.

[shelane]

I have included the text about the use with a CI environment.

[nedsbeds]

Maybe substitute in fin config generate --stack=acquia here. This will set up the project with memcache and solr as well

[lpeabody]

Good call, makes sense given what we're integrating with...

[shelane]

Added with the preferred fin config set DOCKSAL_STACK=acquia.