Learn now how to install and configure Laradock, which is, as presented in the Introductory Article, a project for quick and simple configuration of PHP Web Systems Development Environments using Docker.

In this tutorial article, we will see more in detail how to install and configure a Laradock environment to work by PHP project, that is, an installation for each project . Or how to use an installation for multiple projects.

It is still shown how to configure installations to perform different PHP versions for multiple projects.

Requirements

The applications and requirements to install, configure and execute a Laradock environment are:

Installing Laradock for Multiple Projects

This installation is intended to configure a Laradock installation so that multiple projects can use the same configuration of containers.

Cloning the Laradock repository

Start by cloning the Laradock repository anywhere on your machine - I advise you to clone in the folder where you keep your projects at the same level of them:

cd my-workspace
git clone https://github.com/laradock/laradock.git

The structure of your folders should look like the following:

- my-workspace
  - laradock
  - project-a
  - project-b
    ...
  - other projects

Edit the environment file

  1. Edit the configuration file of your Laradock docker environment. Copy the file .env.example to .env
cd laradock
cp .env.example .env
  1. Open the .env file and make sure the variable app_code_path_host, at the beginning of the file, is pointing to the path of previous level path:
APP_CODE_PATH_HOST=../

This configuration defines the path of your applications on the local machine, this means that they are at an earlier level of folder compared to the Laradock folder. So you should make the clone as explained in step 1.

  1. Configure the .env file with the other settings you want for this installation. As a web server to use and extensions of the PHP-FPM and Workspace interpreter.

Configure the paths of websites / projects

  1. Browse in the folders of your Laradock installation, where each subdirectory corresponds contains configuration files or apps from the application corresponding to the folder name.

Go to the web server you have chosen to use: Apache or NGINX, and create configuration files to point to different project directories of your machine you want to serve with the installation of Laradock:

For Nginx go to nginx/sites, for apache2 apache2/sites.

Laradock by default includes some sample files for you to copy app.conf.example, laravel.conf.example and symfony.conf.example.

  1. Change the default names *.conf:

You can rename configuration files, design folders, and domains as desired, just make sure the root in the configuration files is pointing to the correct design folder name.

6.1. For example: you will use Apache2 and the name of one of the applications is customers and is being developed in Laravel:

6.1.1. access the apache2/websites folder of the Laradock installation

6.1.2. Copy the sample.conf.example file to customers.conf

6.1.3. Change the configuration content in the new file:

<VirtualHost *:80>
  ServerName customers.test
  DocumentRoot /var/www/customers/public/
  Options Indexes FollowSymLinks

  <Directory "/var/www/customers/public/">
    AllowOverride All
    <IfVersion < 2.4>
      Allow from all
    </IfVersion>
    <IfVersion >= 2.4>
      Require all granted
    </IfVersion>
  </Directory>

</VirtualHost>

See how we define DocumentRoot and directory based on the root Apache configuration file for Laradock installation, and we point to the public subdirectory as it is a Laravel application that should have its access point in this directory and not in the application root.

  1. Add the domains to hosts file.

In the hosts file of your machine, configure the localhost IP to point to each project set to your *.conf web server files in the Laradock installation.

127.0.0.1  customers.test
127.0.0.1  another_project.localhost
...

Note that you can use local domain extensions such as: .localhost, .invalid, .test, or .example. But can’t use the .dev extension.

Read Domain extensions to use in local development to understand why.

Using Laradock

Before you start using your recent Laradock installation, be aware of the following:

  • If you are using the Docker Toolbox (VM), I advise to use the Laradock V.4, for this, update of Docker Native to Mac/Windows (recomended). If necessary, check out the documentation as how to update Laradock.
  • I recommend using a version of the more recent Docker than 1.13.
  • If you used an older version of Laradock, it is highly recommended to rebuild the containers you need. Read how torebuild a container on doc.

Configure the .env environment file

After installation and basic configuration you must understand how to configure your environment and the steps to up the Docker containers in everyday life.

  1. If you haven’t done it yet, copy the .env.example file to .env and set up the installations you want for your Docker services as well as the PHP version.
cd laradock
cp .env.example .env

Edit the .env file to choose which software you want to install in your environment. You can always consult the docker-compose.yml file to see how these variables are being used.

Depending on the host operating system, the value provided to compose_file may be required. When you are running the Laradock in Mac OS, the correct file separator to be used is :. When running the Laradock from a Windows environment, several files must be separated with ;.

By default, containers that will be created have the name of the current directory as suffix (for example, laradock_workspace_1).

This can cause “data mixture” within container volumes if you use Laradock in multiple projects. To avoid this change the variable compose_project_name to something unique, such as the name of your project.

I keep the value as laradock even for all my projects in a shared Laradock installation.

# Define the prefix of container names. 
# This is useful if you have multiple projects that use laradock 
# to have separate containers per project.
COMPOSE_PROJECT_NAME=laradock

This is because I do not use path overlap or databases name in databases.Another reason to use the same name in this case is to share service containers, such as MySQL, between different PHP-FPM versions.

Start the Docker containers

  1. Create the environment and execute it using docker-compose

In this example, we will see how to execute NGINX (Web Server), MySQL (Database Mechanism) to host Web scripts in PHP and Redis (cache database):

docker-compose up -d nginx mysql redis

Want to work with Apache (Web Server), MongoDB (Non-Relational Database Mechanism) and Redis?

docker-compose up -d apache mongodb redis

Note: All containers of web server nginx, apache ..etc depend on php-fpm, which means that if you perform any of them, they will automatically start the container php-fpm. In this way it is not necessary to explicitly call the up the php-fpm command.

If you have to do this, you may need to execute them as follows:

docker-compose up -d nginx php-fpm mysql

My most common configuration for use of containers is with Apache and Mariadb or Apache and PostgreSQL. Not forgetting that I always use redis also:

docker-compose up -d apache2 workspace redis mariadb

In the example above you can change mariadb by postgresql or use the extension postgis (with that name).

You can select your own combination of existing containers, listed here.

Running Composer and PHP Artisan

  1. Access the Workspace container, using a terminal Shell, where you can execute commands as: Artisan, Composer, PHPUnit, Gulp, Node, Npm, etc.

You can choose to use Bash:

docker-compose exec workspace bash

I prefer to use a terminal Zsh:

docker-compose exec workspace zsh

Alternatively, for Windows PowerShell users: Run the following command to access the terminal of any running container:

docker exec -it {workspace-container-id} bash

TIP: I advise you to access containers with the default user, ladock, so that the created files have the proper permission level. If you access without defining the user, root is used.

To access the shell as a user laradock, add --user=laradock. Example:

docker-compose exec --user=laradock workspace bash

But, if you need to access a container with privileged access, do not inform the user.

Configure your project

  1. Update the configuration of your project to use the database server, the Redis Service, and others that are installed and are running.

Open the .env file from your PHP project or any configuration file that your project uses, and set the host of the db_host database as mysql.

You need to use the standard Laradock database credentials, which can be found in the .env file (eg: MYSQL_USER =).Or you can change them and rebuild the container.

An example of .env file of a Laravel project configured to access mysql from a Laradock container:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=meubd
DB_USERNAME=default
DB_PASSWORD=secret

Access your project

  1. Access your project in your browser, visit your local host address according to the site setting you have defined.

In the example of this article the project path in the browser would be http://customers.test.

Here’s how to configure some of the options in .env

File settings .env

Some settings are worth mentioning and should be verified by you, adjusted if necessary, in the environment file.

Note that specific settings to enable or not to use each application should be performed so that you can use your containers.

For example, to enable the use of Xdebug in the workspace, you must go to the WORKSPACE section and change the variable WORKSPACE_INSTALL_XDEBUG to True.

The same goes for extensions that should be available for PHP-CLI in the workspace.

To enable PHP-FPM extensions, navigate to your section and enable the extensions you want for the PHP-FPM container.

APP_CODE_PATH_HOST

It defines the path of your application code (s) on your host (your machine and not the container).

You should change it according to the Orange Installation strategy, see the previous sections to understand what values to use.

The list is organized in alphabetical order, but the variables are arranged in different order in the .env file.

DATA_PATH_HOST

Defines the storage path on your machine.

For all storage systems. This means that databases, caches, and other usage files in the applications installed on your containers will be stored in this Path.

Applications will use their subdirectory from this configuration, by default it is ~/.laradock/data.That is, from your folder /Home/Yourusuario/ `is created the hidden directory for configurations and data.

If you are using the strategy of a Laradock installation by PHP version, or even a project installation, you can maintain the same data path setting for all facilities.This way you can share database files and others.

COMPOSE_PROJECT_NAME

Defines the prefix of container names.This is useful if you have multiple projects that use Laradock to have containers separated by project.Or even a PHP version is used.

PHP_INTERPRETER

The PHP interpreter you want to use and may be HHVM or PHP-FM.I confess that I only used PHP-FPM.

PHP_VERSION

Defines the PHP version of the Workspace and PHP-FPM containers (does not apply to HHVM).

For each Laradock installation, when using one per version, you can configure a different version for PHP, but keep the same version to, for example, the MySQL database management system.

This strategy allows you to run containers in different PHP versions but that share the same containers for other applications. This is the beauty of Docker.

Configure Database

In the next section you will learn how configure databases.