Setting Up Laravel Project Using Docker | Step-by-Step Guide

Until recently, I used to run my Laravel projects locally using XAMPP or WAMP. Through my development journey with the mentioned softwares, I came across different challenges while creating my web applications. The challenges that I faced included:

1. Configuration is global, I could only run one server configuration at a time
2. Changing versions of installed software was difficult e.g., swapping from PHP 7 to PHP 8
3. Installing PHP extensions was a pain in the a$$ unless they were packaged with XAMPP (e.g., try installing xdebug or imagick)
4. Running multiple websites each with their own PHP version was difficult to set up.
5. Developing with a valid SSL certificate was hard

These challenges are endless thus I was forced to switch to Docker for my development.

In this article, I’d like to share with you the step-by-step guide for setting up your Laravel Project using Docker.

What is Docker?

Docker is a popular open-source tool that provides a portable and consistent runtime environment for software applications. Docker uses containers as isolated environments in user space that run at the operating system level and share the file system and system resources.

To containerize an application refers to the process of adapting an application and its components in order to be able to run it in lightweight environments known as containers. Such environments are isolated and disposable, and can be leveraged for developing, testing, and deploying applications to production. Containerization consumes significantly fewer resources than a traditional server or virtual machine.

Why Use Docker?

I know most of you are wondering, “Why the hell should I use Docker if my Laravel application works fine on other local servers?” Well, after using Docker for three months, I came to a conclusion that the reason as to why most developers opt to use containerizing programs is that they have a variety of advantages which include:

1. Rapid Performance — Although virtual machines are an alternative to containers, containers do not contain an operating system (whereas virtual machines do), which implies that containers have a considerably smaller footprint and are faster to construct and start than virtual machines.
2. Portability Across Machines — You may deploy your containerized program to any other system that runs Docker after testing it. You can be confident that it will perform precisely as it did during the test.
3. Scalability — If the demand for your apps necessitates, you can quickly generate new containers. You can use a variety of container management techniques when using multiple containers.

Prerequisites

My goal in this post is to help you create a Laravel development environment that is lightweight, fast and that which does not depend on anything being globally installed on our local machine (other than docker itself). In short, we are going to build a Laravel application with:

• No installation of XAMPP, WAMP or similar programs
• No globally installed PHP
• No globally installed Composer

The only requirements that you need are:

1. PC running the latest OS (MacOS, Linux, Windows 10 or Windows 11) with a minimum RAM of 8 GB (Recommended: 16 GB)
2. You — soon-to-be docker user

For this post I will be using Windows operating system. Now, let’s get started.

Step 1 — Install WSL 2

WSL2 (Windows Subsystem for Linux version 2) is a new version of the architecture that allows you to use Linux on top of Windows 10 natively (using a lightweight virtual machine) and replaces WSL.

The feature runs an actual Linux kernel in this new version, which improves performance and app compatibility over the previous version while maintaining the same experience as the first release.

To install WSL 2 on Windows 10 you need:

• Windows 10 May 2020 (2004), Windows 10 May 2019 (1903), or Windows 10 November 2019 (1909) or later
• A computer with Hyper-V Virtualization support
• If you are using Windows 10, the first requirement is not necessary (lol)

To install Windows Subsystem for Linux on Windows 10, use these steps:

• Open Start on Windows 10.
• Search for Command Prompt or Windows Powershell, right-click the top result, and select the Run as administrator option.
• Type the following command to install the WSL on your Windows machine and press Enter:

wsl --install

• Restart your computer to finish the WSL installation.

The above command will install all the WSL 2 components and the Ubuntu Linux distribution.

To install a specific Linux distribution, run:

wsl –install -d DISTRO-NAME.

To update the WSL2 kernel, run the command below:

wsl –update

For more details about WSL2 installation, kindly read the documentation.

Step 2 — Download & Install Docker

1. To start using docker desktop, first you need to download the docker file for windows.
2. Your docker downloaded file can be found in your download folder.
3. Run the set up as Administrator.
4. Follow the Install Wizard: accept the license, authorize the installer, and proceed with the install.
5. Click on the Close button once the installation process is finished.
6. Ensure that your docker user account and administrator account should be the same, otherwise you need to add your user account to the docker user group.
7. After following all these steps, restart your computer to update and start docker desktop on your windows machine.

To ensure that WSL 2 is running on your docker desktop app:

• Start Docker Desktop from the Windows Start menu.
• From the Docker menu, select Settings > General.

• Select the Use WSL 2 based engine check box. (If you have installed Docker Desktop on a system that supports WSL 2, this option will be enabled by default.)
• Click Apply & Restart.

That’s it! Now docker commands will work from Windows using the new WSL 2 engine.

Step 3 — Grab the latest Laravel release

Now that we have installed Docker Desktop successfully and Windows Subsystem for Linux 2 (WSL2) is installed and enabled, the next step is to create our first Laravel project.

• Open your Windows Terminal as Administrator.
• Head over to the location where you want to your Laravel project to be stored.
• Initialize WSL in that location by running the following command:

wsl

• To create a new Laravel application in a directory named “example-app”, you may run the following command in your terminal:

curl -s https://laravel.build/example-app | bash

You can change “example-app” in this URL to anything you like — just make sure the application name only contains alpha-numeric characters, dashes, and underscores. The Laravel application’s directory will be created within the directory you execute the command from.

Sail installation may take several minutes while Sail’s application containers are built on your local machine.

Step 4— Starting the services

Laravel Sail provides a simple command-line interface for interacting with Laravel’s default Docker configuration.

After the project has been created, you can navigate to the application directory and start Laravel Sail.

cd example-app
 
./vendor/bin/sail up

Once the application’s Docker containers have been started, you can access the application in your web browser at: http://localhost.

By default, Sail commands are invoked using the vendor/bin/sail script that is included with all new Laravel applications. However, instead of repeatedly typing vendor/bin/sail to execute Sail commands, you may wish to configure a shell alias that allows you to execute Sail's commands more easily:

alias sail='[ -f sail ] && sh sail || sh vendor/bin/sail'

Once the shell alias has been configured, you may execute Sail commands by simply typing sail. The remainder of this documentation's examples will assume that you have configured this alias:

sail up

Before starting Sail, you should ensure that no other web servers or databases are running on your local computer. To start all of the Docker containers defined in your application’s docker-compose.yml file, you should execute the up command:

sail up

To start all of the Docker containers in the background, you may start Sail in “detached” mode:

sail up -d

To stop all of the containers, you may simply press Control + C to stop the container’s execution. Or, if the containers are running in the background, you may use the stop command:

sail stop

To continue learning more about Laravel Sail, review its complete documentation.

Step 5— Install Starter-Kit

To give you a head start building your new Laravel application, Laravel is happy to offer authentication and application starter kits. These kits automatically scaffold your application with the routes, controllers, and views you need to register and authenticate your application’s users.

While you are welcome to use these starter kits, they are not required. You are free to build your own application from the ground up by simply installing a fresh copy of Laravel. Either way, I know you will build something great!

Once you have created a new Laravel application, you may install Laravel Breeze using Composer:

sail composer require laravel/breeze --dev

Once Breeze is installed, you may scaffold your application using one of the Breeze “stacks” discussed in the documentation.

For this setup, we are going to use the Blade stack, which utilizes simple Blade templates to render your application’s frontend.

The Blade stack may be installed by invoking the breeze:install command with no other additional arguments:

sail artisan breeze:install

After Breeze's scaffolding is installed, you should also compile your application's frontend assets:

sail artisan migrate
sail npm install
sail npm run dev

Next, you may navigate to your application’s /login or /register URLs in your web browser. All of Breeze's routes are defined within the routes/auth.php file.

NOTE: I am using sail command because our project is running on docker.

Step 6— Laravel Bootcamp (Bonus)

If you’re new to Laravel, feel free to jump into the Laravel Bootcamp. The Laravel Bootcamp will walk you through building your first Laravel application using Breeze. It’s a great way to get a tour of everything the Laravel and Breeze have to offer.

Conclusion

As a fellow developer once said:

the world is your oyster. Kubernetes? Docker Swarm? World domination? Totally up to you.

I hope this has been a helpful guide — drop a clap and give me a heads up if it helped you out!