Switching from Drupal VM to Docksal

I had the opportunity recently to start using Docksal on a project. We’ve run Drupal VM for the last 9 months—Drupal VM is the standard local development platform for Acquia’s Professional Services team—but as the customer transitions into Docksal for their own uses, I wanted to go through the process as well so I could better understand what the process looked like, and what changed as a result.

Right up front, I should say that I didn’t personally setup Docksal for the project (another architect did that). I only benefited from the work he did. So, in this case, I am installing a Docksal VM that was setup by someone else. We have attempted to capture some of the high level info on the BLT documentation site to help with this process, but it likely needs some additional input.

Workflow Changes

I wanted to capture these right up front, because I’m not sure they have been enumerated anywhere else (yet).

  1. Project location on your machine — for my Drupal VM and most of my other projects, I just store them in ~/git/<project>. For the Docksal project, it seems to only work properly if I have it in the ~/Projects/<project> directory. I think this is a Docker thing? But it did require me to move the entire project directory before things would “work.”

  2. The url will change locally — for my Drupal VM projects, usually the local is at http://local.<project>.com. For the new Docksal project, it is at http://<project>.docksal. Again, a minor change, but an important one.

  3. Controlling the VM — on a Drupal VM most of the commands are vagrant based. Docksal introduces the ‘fin’ command. Most commands need to be executed with fin in front of them (and this definitely is a change for me). So

$ blt setup


$ fin blt setup

Update Process

Obviously, all Docksal requirements must be installed and met on the host machine before continuing. RTFM!

First, I nuked my Drupal VM.

$ blt vm:nuke

This completely removed the vagrant vm from the project.

Next, I did a simple mv on the directory to relocate it from the ~/git directory on my Mac to the ~/Projects directory. (Obviously my IDE and Git GUI needed to be updated to reflect this change.)

From here, I deleted my docroot/sites/default/settings/local.settings.php file (so it could be regenerated) and I spun up the Docksal containers.

$ fin init

This process took only a few minutes to complete. However, I had significant problems on my host system getting communication with the containers to work. After the init call completed, it took me a couple of tries to successfully fin up and get access to the containers.

From here, I was able to fin blt setup and get access to the local.

All in all, the process of switching only took about 15-20 minutes (although I did spend a couple of hours troubleshooting the host vm issue).

In the end, I’m not sure if I managed to sudo away some of my woes, or if provisioning the container in the correct projects folder ultimately was the solution. Will report back if I get more information.