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
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 | sh
This 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/docksal
For 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
To speed up this process, use the following one-line command:
echo "DOCKSAL_NFS_PATH=~/projects/docksal" >> ~/.docksal/docksal.env
Step 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 start
It 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 restart
Upon 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)
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.
Then we will clone a basic Drupal 8 project that has Docksal configured,
git clone https://github.com/kanopi/drupal8-composer-docksal drupal8
and change into that project we just downloaded:
Now, initialize the project
If 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 again
then run the update command for the latest version of Docksal:
In 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.980s
Drum 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.
Running this should not cause any issues with mounting the project, and should start your Vagrant project.
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.