July Release Confetti
150+ New Courses, Hands‑On Labs, And
Interactive Learning Activities
Learn More

Setting up LaraDock for Laravel

Introduction

In this guide, you will learn how to set up LaraDock in a Laravel project. LaraDock gives us an easy way to run a Laravel application using Docker in a single command. Before we dive into the basics of LaraDock, let’s gain some context.

What is Laravel?

This guide will not focus on the details of Laravel itself, but you are likely already familiar with it since you’re here. The Laravel Philosophy:


Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable, creative experience to be truly fulfilling. Laravel attempts to take the pain out of development by easing common tasks used in the majority of web projects, such as authentication, routing, sessions, and caching.

via Laravel.com

What is Docker?

While this guide’s focus is not on the core concepts or use cases of Docker, it’s good to have a basic idea of what it is before we dig in. Docker gives us a nice way to prepare an environment to handle a particular task without being invasive to our main operating system. LaraDock uses Docker and pre-configured containers to do most of its magic, but the power of Docker goes far beyond this example.
According to docker.com:


Docker containers wrap a piece of software in a complete filesystem that contains everything needed to run: code, runtime, system tools, system libraries – anything that can be installed on a server. This guarantees that the software will always run the same, regardless of its environment.

For a deeper explanation of Docker and its capabilities, check out the Docker Deep Dive course offered by Linux Academy.

What is LaraDock?

Often compared to Laravel Homestead (which uses Vagrant), LaraDock is an open source project that uses Docker to easily prepare the environment you need to run a Laravel application. It’s easy to use and can save a developer’s valuable time. For example: If you project needed to use mongoDB and nginx, LaraDock will be able to prepare the necessary containers with the proper configuration using a single command:

docker-compose up -d mongo nginx

Nice, right? The LaraDock documentation contrasts its use of Docker with Homestead’s use of Vagrant:


Vagrant creates Virtual Machines in minutes while Docker creates Virtual Containers in seconds. Instead of providing a full Virtual Machines like you get with Vagrant, Docker provides you lightweight Virtual Containers that share the same kernel and allow to safely execute independent processes.

In addition to the speed, Docker gives tons of features that cannot be achieved with Vagrant.

Most importantly Docker can run on Development and on Production (same environment everywhere). While Vagrant is designed for Development only, (so you have to re-provision your server on Production every time).

Running a virtual Container is much faster than running a full virtual Machine. Thus LaraDock is much faster than Homestead.

Let’s begin

Before we get going, we need to make sure that you have the necessary tools. You will need to have all of these tools installed and ready to use in your terminal, but you most likely already have what you need:

Prerequisites
  • git - We will use git to clone the LaraDock repository. - Instructions
  • docker - Docker is required for LaraDock to function. - Instructions
  • composer - Optional. I will use composer to create a new Laravel project in this guide, so you will need that if you want follow along. If you already have an existing Laravel project, you are good to go. You may also use the Laravel Installer - Instructions

Notice that you do not need to manually prepare PHP, databases, or any other typical infrastructure dependencies that a Laravel project might need to have installed in your development environment. LaraDock will handle all of this for us!

For the sake of instruction, I’m going create a new Laravel project to show the setup process. Even if you already have a Laravel project I would suggest creating a new one along with me to avoid messing anything up while you learn. If you feel comfortable enough, feel free to use your existing project.

Creating an example Laravel project

Optional, but recommended…

Let’s make a fresh Laravel project to play with. I will be using composer for this in the terminal.


  1. Navigate to a directory where you want to create the project in terminal. In this example, I will be creating a directory at ~/laravel-projects and navigating to it:


     mkdir ~/laravel-projects
    cd ~/laravel-projects

  2. Use composer to create a new Laravel project in this directory. I’m going to call my project example-proj.

  3.  composer create-project --prefer-dist laravel/laravel example-proj
    You will see a good bit out output while the project is created.

    Installing laravel/laravel (v5.3.16)

    • Installing laravel/laravel (v5.3.16)
      ……..

You should see “Application key [base64:...] set successfully“ once it has finished. Run ls to make sure you see a new directory for the project (in this case we should see example-proj).

Adding LaraDock to Laravel project

Now we can install LaraDock into the project. First, navigate into the project directory and use git to install LaraDock. To avoid conflicts when using LaraDock in multiple projects, let’s specify a unique name for its directory in each project. A good convention is to use “laradock-PROJECT_NAME“ (so I will use laradock-example-proj in this example):


cd example-proj
git clone https://github.com/LaraDock/laradock.git laradock-example-proj

Note: If you are installing into an existing Laravel project that uses git, you should use git submodule add instead of git clone in the snippet above.

You can use ls to see the new directory (laradock-example-proj in this example) inside of our project folder. We will need to navigate to this folder to use LaraDock. The reason for this should be clear momentarily.


cd laradock-example-proj

Now we are ready to configure and use LaraDock!

Configuring LaraDock and Laravel

For the sake of example, let’s pretend our Laravel project uses mysql and nginx.

First, we need to tell LaraDock how we want to configure our services (passwords, ports, etc). This is done in a file called docker-compose.yml. Next, we need to tell the Laravel project what those settings were so it can interact with them. This is done in a file called .env.

Using the docker-compose.yml file:

We will be using LaraDock with the docker-compose command. This command will adhere to the properties defined in a docker-compose.yml file.
The LaraDock developers have prepared the directory that we added in the previous step with a default configuration file that can be modified to suit the project’s needs.
Whenever the docker-compose command is used in terminal, it will look for the docker-compose.yml file in the current working directory. This is why we need to be inside of the LaraDock directory for the commands to function properly.


Note: The docker-compose.yml file resides inside of LaraDock’s directory within our project. In our example project, the configuration file is at example-proj/laradock-example-proj/docker-compose.yml

We can modify the configuration defined in the docker-compose.yml file to fit our needs. Let’s open it up in a text editor to poke around. I’ll be using the nano editor in terminal:


nano docker-compose.yml

In practice, you should take the time to configure all of these containers properly, but for this example, let’s just look at the MySQL configuration in the docker-compose.yml file. Here’s the default:


### MySQL Container #########################################
mysql:
build: ./mysql
volumes_from:
- volumes_data
ports:
- "3306:3306"
environment:
MYSQL_DATABASE: homestead
MYSQL_USER: homestead
MYSQL_PASSWORD: secret
MYSQL_ROOT_PASSWORD: root

We can modify the these entries to match our desired settings. Later on when we use the docker-compose command to start things up, LaraDock and Docker will set up the mysql container with these settings. Let’s change the database name, user, and password that it will be set up with:


### MySQL Container #########################################
mysql:
build: ./mysql
volumes_from:
- volumes_data
ports:
- "3306:3306"
environment:
MYSQL_DATABASE: example-proj
MYSQL_USER: example-user
MYSQL_PASSWORD: example-pass
MYSQL_ROOT_PASSWORD: example-root-pass

Save the file and exit.


Note: If you are using nano, use control+X and follow the prompt at the bottom of the terminal window. If it fails to save, you may need re-open the file with sudo (sudo nano docker-compose.yml) and try again.

Now we need to tell the Laravel project how our services are configured.

Using the .env file:

Now that we’ve set up the configuration for the services, we need to tell Laravel everything it needs to know so it can interact with them. Edit the file called .env in the parent directory of the Laravel project (example-proj/.env in this example). Since our terminal’s current working directory is “one directory deep” into our project, we can get to it with ../.env


nano ../.env

You will need to update this information to match what is defined in the docker-compose.yml file that we modified in the previous step. Based on our example setup, we want to make sure these entries are set correctly:


DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=example-proj
DB_USERNAME=example-user
DB_PASSWORD=example-pass

Save and exit the file.

Starting/Stopping services with LaraDock

Now that we have prepared our configuration files, we are ready to use LaraDock. First off, ensure that your terminal’s working directory is inside of the laradock folder within the project. You can check using the pwd command. If not, navigate to it using cd in terminal. Remember that we are pretending that our example Laravel project requires mysql and nginx.

Let’s start them up. We will use the docker-compose up command. Let’s use the -d option to daemonize the services (runs them in the background). We will also specify the services we want to use.


docker-compose up -d mysql nginx

Note: You need to have the Docker daemon started.

LaraDock will now instruct Docker how to prepare our services. This may take some time while the proper dependencies are obtained and built. After all has completed, you should see something similar to this:


Creating laradockexampleproj_volumes_source_1
Creating laradockexampleproj_volumes_data_1
Creating laradockexampleproj_workspace_1
Creating laradockexampleproj_mysql_1
Creating laradockexampleproj_php-fpm_1
Creating laradockexampleproj_nginx_1

Guess what! You’re ready to use your Laravel project. Open your browser and navigate to http://localhost/. You should see the default “Laravel” page from the example-proj!

When you’re ready to stop the services, head back to Terminal. Be sure you’re in the proper directory and run:


docker-compose down

If you refresh http://localhost/ in your browser, you should see that the page is no longer available.


LaraDock supports more than just mysql and nginx. Check out the documentation for more supported services and more commands to make the most out of it.



  • post-author-pic
    Johnny J
    01-09-2017

     @davisengeler: Nice guide!

  • post-author-pic
    Francisco S
    01-09-2017

    Awesome guide Davis! I've never heard of Laradock, so maybe this could be a good moment to try it and see how it works :)

  • post-author-pic
    Davis E
    01-10-2017

     @franverona: Thanks! Christophe introduced me to it (to make the guide, actually) and it seems super convenient for a dev environment. I assume it could be used for production too, but I'd be weary of suggesting it. I don't think that's its intended purpose, and those pre-built containers probably weren't configured with production environments in mind. 

  • post-author-pic
    Mahmoud Z
    07-08-2017

    Amazing article, Thanks.

Looking For Team Training?

Learn More