Setting up an existing Laravel 8 Sail (Docker) project on Windows WSL2 and Ubuntu 20.04

The focus of this tutorial is on prepping a Laravel project where Laravel Sail, Laravel’s own Docker environment is already setup so you can spin up the project through Docker on Windows.

Reading the official Laravel Sail guide will help when ever you get stuck even though its a little long and has a lot of additional information that might throw off a newbie. If you want to add Docker to your new Laravel project or want to start a Laravel sail project, read the complete guide from above, its pretty easy.

These projects already have Sail configured and you can opt to use Php 8.0 or 7.4 as well the MySQL 8 or other versions after configuring those inside the docker-compose.yml file inside the project root directory.

docker-compose.yml sample

I will setup the application within a WSL2 distro. of Ubuntu 20.04. You do not need previous Docker experience to follow this tutorial.

Project repo I used is below (You can use your own Laravel project’s or fork ours and take it for a spin).
https://github.com/achala87/webuildlk. The project helps people setup rating systems for service providers, add history timelines,
blogs and information pages as well has a dashboard for sharing statistics on nations or organizations. It’s basically a civic action platform but you can use it creatively, quite easily for even a business application or web-app.). You are welcome to add a PR and join in. You can see the app in production here www.buildlk.com.

Other projects I’ve added Sail to is the national environmental platform neplk.com.

Benefits of using Docker for your Laravel software project

Docker helps teams work on systems by making setting up projects simpler and less painstaking. Especially if you work on multiple systems at the same time since its otherwise not possible to maintain versions of the development dependencies and tech. stacks for different projects within one environment. And systems like VMware or dual boot is painful, at least more painful than Docker.

Docker creates a container within your Docker environment, and runs the projects dependencies using a docker machine image. On Windows, new builds support WSL/ WSL2 which allows windows to host Linux subsystems which Docker can use to run your docker systems.

This means if you make a mistake, you can simply delete a container and restart one as necessary within a few minutes.

Step 1 — Prerequisites : Installing Docker and Ubuntu 20.04 on WSL2 on your machine

1. Install the latest Docker version (https://docs.docker.com/docker-for-windows/install/) and enable WSL2 (https://docs.microsoft.com/en-us/windows/wsl/install-win10).
2. Navigate from your windows search bar to the Microsoft store (https://aka.ms/wslstore) and search for the Ubuntu distribution you like i.e. Ubuntu 20.04 and install it.

Step 2 — Connecting Docker with your Ubuntu 20.04 image

Open your Docker app, go to settings and then Resources and toggle the Ubuntu 20.04 image to on state. And that’s it now your docker containers can use the Ubuntu distribution to mount project.

Make sure the WSL2 based engine is selected in settings

Enabled the Ubuntu integration to Docker

Step 3 — Pulling in your project.

Open the Ubuntu 20.04 console from your windows OS and clone the project, it pulls the project repository to the home directory of the Ubuntu image. If your using a visual tool like GitHub desktop it gets pretty easy as well.

$ git clone https://github.com/achala87/webuildlk.git

Open an Ubunto 20.04 terminal from your Windows start menu and clone the repository

You can quickly open your wsl root where your Linux images are found by running the following command into your Folder explorer navigation row.

 \\wsl$\

If you want to open and see your Ubuntu 20.04 root folder directly from your Ubuntu 20.04 console using the following command.

explorer.exe .

You can open your favorite coding tool vs code by running the following code from the Ubuntu 20.04 console

code .

Step 4 — Your Projects docker-compose.yml file — what does it do?

Next open you docker-compose.yml file in the root of your application.

This references files inside the /vendor folder and defines versions of services your docker container should load. You can mainly change the PHP and MySQL versions here. I set them usually to PHP 8 and MySQl 8.

So remember this is a file you don’t re-commit to the upstream as its specific to your distribution. Just like the .env file is.

https://docs.docker.com/compose/ to learn more about the docker-compose function.

Step 4 — Installing composer packages

The project consists of a composer.json which lists the dependencies of your project. To run sail and other requirements, usually which will install those packages in to your /vendor folder. Learn more about composer here.

Copy and paste the following command into to your Ubuntu 20.04 console and hit enter. It will run a docker image with PHP 8 and composer to run the composer installation.

docker run — rm \
 -u “$(id -u):$(id -g)” \
 -v $(pwd):/opt \
 -w /opt \
 laravelsail/php80-composer:latest \
 composer install — ignore-platform-reqs

Right after, as a good habit I also do a composer update using the following command.

docker run — rm \
 -u “$(id -u):$(id -g)” \
 -v $(pwd):/opt \
 -w /opt \
 laravelsail/php80-composer:latest \
 composer update — ignore-platform-reqs

Next its a good practice to composer dump-autoload to refresh your packages on vendor/autoload.php.

docker run — rm \
 -u “$(id -u):$(id -g)” \
 -v $(pwd):/opt \
 -w /opt \
 laravelsail/php80-composer:latest \
 composer dump-autoload — ignore-platform-reqs

After this you might have to rename the .env.example to .env.

Enter the values of .env as necessary and save it. If at a later stage Laravel complains there is no key, you will have to run : php artisan key:generate

docker run — rm \
 -u “$(id -u):$(id -g)” \
 -v $(pwd):/opt \
 -w /opt \
 laravelsail/php80-composer:latest \
 php artisan key:generate — ignore-platform-reqs

Step 5 — Add alias for sail in .bashrc inside ubuntu home of user

Then I also added an alias for ./vendor/sail/up command inside the Ubuntu 20.04 so its easier to use than the longer command needed to execute sail commands like turning up the container.

Goto the root of your Ubuntu environment.
Run vim ~/.bashrc

vim ~/.bashrc

find the alaises section and add the following line and save the file.
alias sail=’./vendor/bin/sail’

then :wq to save and exit the file (.bashrc) editor.

Step 6 — Run the Docker container and see your project running.

Go into your project directory (cd projectName) and run Sail up from the Ubuntu console. Remember all your commands are run from this command shell.

The container should run and you can see the container and services in side your docker desktop. You can access your project from the docker desktop icons below or directly from the browser url:port.

Step 7 — Connecting to your database.

Ok now that your docker is running and you can see the webserver and the database server on Docker Desktop, its time to login to your database and see the migrations do their magic.

If your project uses MySQL, you can use a tool like MySQL Workbench.

MySQL Workbench configuration.

Open work bench and use the credentials from the .env file. You should be able to log in.

I used the following.

DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=buildlk
DB_USERNAME=root
DB_PASSWORD=

This is important, you must create the database for the migrations to run manually by logging in to the mysql database through MySQL Workbench. Make sure the database name is the same as the one you provide in .env file

Next run in a terminal you open inside your project within vscode/ on a ubuntu terminal (make sure you have cd inside your project)

1. sail php artisan migrate
2. sail php artisan key:generate
3. sail php artisan db:seed         #only if your project has seeding data

H3: Running Artisan commands and other packages

To run artisan, composer, and npm commands, the sail alias should come first.

Instead of:
php artisan migrate

You should:
sail artisan migrate

Database Migrations and Seeders

Your project should have database migrations and data seeders which help you get started. Your projects .readme file will usually guide you on how to do this. Migrations creates the database tables and seeders would add seeding data so you can login as users and see data populated in your application.

Other useful commands that will help your coding life are also given here.

docker ps — all : shows all containers in the system. Some time your need to remove earlier versions if things don’t work as expected.

docker container rm YOUR_CONTAINER_ID : to delete a container.

docker-compose down -v : Stops containers and removes containers, networks, volumes, and images created by up .

docker-compose up -d : docker-compose up command aggregates the output of each container.

php artisan config:cache and php artisan cache:clear : clears the config cache in Laravel.

You can reach me through softwareconsultant.info or directly at hello@softwareconsultant.info for Laravel based services and other technology services in ReactJS, NodeJS, Wordpress, Shopify and AWS.