How to install an existing laravel project using Sail / Docker

Installing an existing Laravel project when a new team member comes on board is usually pretty straightforward if they are using the same setup as you. I.e. a Mac. But what if they are using Windows? You'll probably need to reach for Docker. Laravel also comes with a first party package called Sail, which makes setting up and running a Laravel project that little bit easier.

I used to hate this as getting a project setup on a Windows machine was an absolute nightmare of back and forth, tweaking settings. But no more, if I just spent more time reading the documentation. I'd have saved myself so much hassle. Anyway, enough waffle. Let's do it!

Step 1 - Install all the required dependencies

This still takes a while to set up, but if you do it in the right order, you get way less mistakes. Make sure you have the following programs installed:

1. Docker Desktop
2. Windows Subsystem for Linux (WSL2)
3. Ubuntu 22.04 from the Windows Store
4. Make sure Docker Desktop is configured to use WSL2. Normally this is already done, but worth checking.
5. Windows Terminal - So you can open up your Linux (Ubuntu) terminal
6. Visual Studio Code and the Remote development extension - You don't need VS Code, but the process is pretty streamlined. So I'd recommend using it.

All in this will be a couple of GBs to download, you'll also have to restart your machine at least once. (Buy a MacBook instead!)

Step 2 - Get your SSH keys setup

Now that you've got all the software you'll need, it's a good time to set up your SSH keys so that you can pull down your code / project from your source control. (GitHub, Bitbucket, Gitlab etc)

Even if you don't use GitHub, they have a good guide on first checking for existing keys and if not, how to create one and add it to your ssh-agent.

One key thing to remember here is to use the Ubuntu terminal from within the Windows Terminal app you downloaded earlier. Next to the new tab icon is a downwards facing arrow, click on this and it will show a list of available terminals. Make sure you choose Ubuntu 22.04 from this list. Then go and create your SSH key.

Next go to your source control provider and add your key to your account. It will be slightly different for each provider, but you can use your Google skills to find out what you need to do here. Also make sure you have permission to access the repository / project. Otherwise you won't be able to clone down the code!

Step 3 - Install your composer dependencies

Once you've cloned down your project, using your Ubuntu terminal - cd or change directory to your project and open it up in VS Code. You can type in code . in the terminal and it should open up VS Code and it should automatically fire up the Remote development extension. Happy days!

Anyhow this part was always the hardest / most annoying part for me. A Windows machine is very unlikely to have PHP installed let alone Composer too. But to get composer you need PHP. I'm not very ashamed to say that I just went ahead and installed the version of PHP I needed on Ubuntu and then downloaded composer from there. It turns out you don't need to do this.

There's this thing called Docker which is meant to take away all the overhead of needing to install all these programs on your computer. It never once occurred to me that I could use Docker to pull down PHP and composer in one go and throw it away when I'm done. There's also this little gem tucked away in the Laravel Sail docs which does exactly what I needed.

docker run --rm \
    -u "$(id -u):$(id -g)" \
    -v "$(pwd):/var/www/html" \
    -w /var/www/html \
    laravelsail/php82-composer:latest \
    composer install --ignore-platform-reqs

Make sure you change the laravelsail/php82-composer part to be the version of PHP that you need. laravelsail/php81 for PHP8.1 for example.

Run this code snippet in the same directory as your freshly cloned project (Ubuntu terminal don't forget!) and it will spin up a PHP container and do a composer install for you, pulling down all your projects dependencies. Lovely stuff!

Step 4 - Environment setup and Sail away!

The next parts will be to set up your .env file and any other things that are required to get your project running. You might need to speak to your team members on what config you need.

A part that might catch you out is the Database setup. When you run sail for the first time, it creates two databases for you, the first is a database whose name is based on the value in your DB_DATABASE .env value. and the second is a dedicated testing database. It will also create the database with the password from your DB_USERNAME and DB_PASSWORD values. So when you go to connect to your database, use these values. But what might happen is that you forget to update these values. Annoyingly you can't just update these details after you've run sail up. You'll have to stop sail and then delete your MySQL volume within docker first and then do sail up.

Once you've got all your composer and .env file stuff sorted out run the following command in your Ubuntu terminal: ./vendor/bin/sail up -d On the first run this will take a long time to download everything, any other time it's fairly quick. That's it. You should be all good to go and if you're not, throw your Windows laptop out the window and buy a MacBook Air instead.