Adds documentation for the Docksal environment

[shelane]

I wasn't sure which branch to propose the PR for. It's here for 9.2.x, but should certainly be included in 10.0.x also.

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.

[lpeabody]

I would elaborate on what setup.strategy means here. By default, passing this option is not required since BLT defaults to the install strategy.

Maybe specify something along the lines of:

Alternatively, you may use a sync setup strategy if there is an existing remote with a source database to used in a Drush sql:sync operation:

fin blt setup -D setup.strategy=sync

[lpeabody]

Hm, reconsidering my above comment on using setup.strategy=sync, it's probably better to add that to this section. I would document it as such:

3. Assuming your site's drush remote is @sitegroup.siteid then you can update your BLT configuration (either at the project level or site level):

At the project level (blt/blt.yml) or site level (e.g. sites/default/blt.yml):

setup:
  strategy: sync

drush:
  aliases:
    remote: sitegroup.siteid

So when setting up the project for the first time when running fin blt setup it will execute the sync setup strategy rather than the install strategy (sql:sync vs site:install), effectively executing drush sql:sync @sitegroup.siteid @self.

[mikemadison13]

We should also add a link to https://blt.readthedocs.io/en/latest/local-development/#alternative-local-development-environments that links to Docksal as well as Lando (and perhaps take the opportunity to fix the broken markup for the Lando link that's there too!)

Thanks @shelane for taking time to put this together

[shelane]

@mikemadison13 I added the link on the local development page and fixed the markup.

[mikemadison13]

@shelane can you have a look and respond to @lpeabody's comments above? i'm not sure i've ever passed an argument into blt setup before, not sure how that would be needed in this context?

[lpeabody]

@mikemadison13 technically speaking you don't need to pass arguments. Setup strategy is not unique to Docksal obviously, so documenting it here is probably out of scope (BLT would be well served to highlight setup strategy elsewhere in the documentation for sure), but altering the setup strategy (valid strategies being install, sync, and import) has been an indispensable tool to use in our CI processes which also run through Docksal.

To that point, I think it's relevant for Docksal users. Maybe in a separate CI section?

[shelane]

Closed in favor of #3268