If you work on multiple projects at once, or need to collaborate with other developers (as many of us do), then getting your development environment up and running quickly can be crucial to your ability to make efficient progress.
For the past few years, the best tool to help you do that was Vagrant. Vagrant interacts with Virtual Machines. One of it’s greatest features is that most of the configuration can happen in a vagrantfile, which can then be committed to your project. This allows developers to easily clone a project and get a development environment up and running without any special configuration.
Now Docker is the new kid on the playground. Docker provides the ability to have thin containers which focus on a specific service, whether that’s MySQL, Nginx, Apache, or testing applications like Behat, and Selenium. So now we have smaller containers, without the same overhead as that of a traditional Virtual Machine.
Sounds great, right? Well yes, but now your existing tools may need to interact with Docker. Or maybe you’ve run into a need for both Docker and Vagrant to co-exist with each other, depending on your needs. The good news is that there is a solid way of making this happen!
In this post I’ll walk you through installing Docksal and setting it up so that Docker can work side by side with Vagrant. All of the following steps have been tested on macOS going through a command line.
Installing and Configuring Docksal
We’ll start with the basics.
Step 1: Installing Docksal
The first step is making sure you install Docksal. To do this, you can use the handy one-liner below.
curl -fsSL get.docksal.io | shThis line of code will install the Docksal command fin and, if needed, will install Virtualbox. That means there’s no need to go out and install Docker ahead of time. Note: If you already have Vagrant and Virtualbox installed it may be best for you to shut down all VMs as the installation can sometimes hang in the process.
Step 2: Create the Projects Folder to House Development
Next, we have to configure the directory that the Docksal VM mounts for use with Docker. By default, Docksal will attempt to mount just the /Users directory. The problem with this is that if you have a Vagrant VM mounted anywhere within the the same same folder hierarchy then it will cause an error. So, you’ll need to tell Docksal to mount a folder deeper within the structure that isn’t already being mounted.
mkdir -p ~/projects/docksalFor this example, we will place a folder within our user’s home directory labeled projects. Sometimes this folder will already exist. If so, you could just change into that directory.
Create a Docksal directory to house all of the Docksal projects. The name of this folder is arbitrary. For this example we will use a simple name. This folder’s main purpose is to hold all of your Docksal projects. This is also the data that will get mounted to your projects when they are started.
Step 3: Configuring Mounted Path
Once we have created the folder hierarchy for our projects, we have to tell Docksal what folder to mount into the VM, so we’ll have to add the following line to our global docksal.env file which is located in ~/.docksal/docksal.env
DOCKSAL_NFS_PATH=~/projects/docksalTo speed up this process, use the following one-line command:
echo "DOCKSAL_NFS_PATH=~/projects/docksal" >> ~/.docksal/docksal.envStep 4: Start Virtual Machine
After we’ve added the DOCKSAL_NFS_PATH line, now comes the process of starting our VM. Running the vm start command will make sure that the VM is running. The following command can be run from any folder in a terminal window.
fin vm startIt should result with a similar response:
Starting "docksal"...
(docksal) Check network to re-create if needed...
(docksal) Waiting for an IP...
Machine "docksal" was started.
Waiting for SSH to be available...
Detecting the provisioner...
Started machines may have new IP addresses. You may need to re-run the `docker-machine env` command.
Enabling automatic *.docksal DNS resolver...
Clearing DNS cache...
Configuring NFS shares...
NFS shares are already configured
Mounting NFS shares...
Starting nfs client utilities.
Mounting local /Users/example/project/docksal/ to /Users/example/project/docksal/
Importing ssh keys...
Identity added: id_rsa (id_rsa)If you happen to get the following message:
Machine "docksal" is already running.then a restart may be necessary, which can be done using the this command:
fin vm restartUpon a successful restart, you should see a similar response:
Stopping "docksal"...
Machine "docksal" was stopped.
Starting "docksal"...
(docksal) Check network to re-create if needed...
(docksal) Waiting for an IP...
Machine "docksal" was started.
Waiting for SSH to be available...
Detecting the provisioner...
Started machines may have new IP addresses. You may need to re-run the `docker-machine env` command.
Enabling automatic *.docksal DNS resolver...
Clearing DNS cache...
Configuring NFS shares...
NFS shares are already configured
Mounting NFS shares...
Starting nfs client utilities.
Mounting local /Users/example/project/docksal/ to /Users/example/project/docksal/
Importing ssh keys...
Identity added: id_rsa (id_rsa)Want to learn more? Contact us.
Testing Configuration
Step 1: Start Docksal Setup
Now comes the fun part where we get to test our new configuration. Was it successful? Let’s see if our work has paid off and get our first Docksal project up and running.
Start by navigating to the project folder that was created in the previous steps.
cd ~/projects/docksalThen we will clone a basic Drupal 8 project that has Docksal configured,
git clone https://github.com/kanopi/drupal8-composer-docksal drupal8and change into that project we just downloaded:
cd drupal8Now, initialize the project
fin initIf you previously had Docksal installed and the following error appears on your screen,
Minimal fin version required is: 1.22.0
Please run fin update and try againthen run the update command for the latest version of Docksal:
fin updateIn this project, we have a basic initalize command that will use composer to download all of the libraries. Don’t have composer? Don’t worry, composer will get installed in the container. Drush then runs the site-install command.
Want to know if this command worked properly? Did you get results like this? If so, great!
Step 1 Initializing stack...
Removing containers...
Removing drupal8_web_1 ... done
Removing drupal8_db_1 ... done
Removing drupal8_cli_1 ... done
Removing network drupal8_default
Removing volume drupal8_project_root
Volume docksal_ssh_agent is external, skipping
Starting services...
Creating network "drupal8_default" with the default driver
Creating volume "drupal8_project_root" with local driver
Creating drupal8_cli_1 ...
Creating drupal8_cli_1
Creating drupal8_db_1 ...
Creating drupal8_cli_1 ... done
Creating drupal8_db_1 ... done
Creating drupal8_web_1 ... done
Waiting for drupal8_cli_1 to become ready...
Connected vhost-proxy to "drupal8_default" network.
Waiting 10s for MySQL to initialize...
Step 2 Initializing site...
Making site directory writable...
/var/www/docroot/sites/default/settings.local.php already in place.
You are about to DROP all tables in your 'default' database. Do you want to continue? (y/n): y
Starting Drupal installation. This takes a while. Consider using the --notify global option. Installation complete. User name: admin User password: 7yDUeUyVvH
Congratulations, you installed Drupal!
real 0m22.527s
user 0m6.640s
sys 0m2.980sDrum roll… Open a browser to http://drupal8.docksal and you should see a freshly installed Drupal 8 site.
Step 2: Confirming Vagrant is Intact
For this step, we won’t be able to guide you through the process since all projects are different. The easiest way to confirm is to navigate to one of your Vagrant projects, then stop and restart the project.
vagrant haltvagrant upRunning this should not cause any issues with mounting the project, and should start your Vagrant project.
Summary
To summarize, we completed a basic Docksal install. The one liner was installed which can usually accommodate, unless you are also running Vagrant. In that case we modify the folder which mounts to the Docksal VM. The reason for this is that NFS exports can’t overlap. By default, Docksal uses /Users which can cause an issue, as most, if not all the projects a developer does in Vagrant are usually in that User’s directory.
What this also means is that all Docksal projects will have to live within the DOCKSAL_NFS_PATH folder, because when Docksal uses the minimal VM layer on virtualbox it’s only mounting that one folder, whereas Vagrant projects are mounting individual projects to their respective VM.
We also ran a test to make sure we could get a basic Drupal 8 installation. This provides a good starting point when testing development within the Docksal system.
