tl;dr
If you'd like a more visual aide, I've published a video which follows along with this tutorial in depth. It shows you all of the steps, and explains how best to use the above commands in the finished running network.
Want to skip the detailed tutorial altogether and dive into this yourself? Install Docker for your OS, clone this repo, add your Laravel app files to the src directory, and from the root project directory you just cloned run:
docker-compose up -d --build.
You can then use Composer, NPM, and Artisan commands like so:
docker-compose run --rm composer require aschmelyun/larametrics
docker-compose run --rm npm install --save vue
docker-compose run --rm artisan migrate
Some backstory
This tutorial is built on a previous one that I wrote a few months back called The beauty of Docker for local Laravel development. While this article is beginner-friendly, it leaves out a lot of the original setup for the nginx, php, and mysql containers. I'd recommend that you start off with the previous tutorial first, and then move on to this one.
After producing that original tutorial and uploading the Docker repo to GitHub, I started receiving regular questions from the community at large about how to do certain things within the container network. The biggest ones could be boiled down to:
"How do I run {Composer|NPM} if I don't have {PHP|Node} installed on my local machine?"
Unfortunately, I had to come back with an "I don't really know right now, but I'll find out!". I did some digging, and just 48 hours later I had a solution that worked. At least, for every use case I regularly use when developing Laravel applications, and without having to have anything besides Docker installed on my computer.
This will expand on the previous docker-compose.yml file and add three new containers, in addition, you'll learn how to easily run Composer, NPM, and Artisan commands on your console through the container network.
Let's get started!
Adding Composer
Starting off easy, this container is made from a pre-built image available on the Docker hub. Before we make any changes, if your Docker network is up, bring it down with docker-compose down. Let's open up our docker-compose.yml file, and add this block defining the Composer container under the last service:
composer:
image: composer:latest
container_name: composer
volumes:
- ./src:/var/www/html
working_dir: /var/www/html
depends_on:
- php
networks:
- laravel
Most of these headings and values should be pretty familiar to you, however there's one that sticks out as new for this container: working_dir.
See, by default, the Composer container expects the site files to be available in a particular directory (I think this is /data by default, but I'm not 100% sure). Now, we could just change the volume to mount at /data instead of /var/www/html, but I like keeping things synced up across my container network. Instead, working_dir lets us overwrite the default directory Composer looks in, replacing it with where our application's files are actually located.
If we bring our container network back up with docker-compose up -d, we can see that the Composer container is built alongside our others and brought up as expected. Now, here's where the fun happens.
Using the following command, we can tell Docker to spin up the Composer container, and run a command with the same namesake as the service (e.g. composer), inside of it. Then, once the job has completed, the container is brought back down and any memory freed up. That command is:
docker-compose run --rm composer require aschmelyun/larametrics
Of course, you can replace require aschmelyun\larametrics with any other Composer command you want to run, but the point is that this all takes place isolated inside the container, makes the necessary changes to your application's file structure, all without having to have PHP or Composer installed locally.
Let's keep it going!
Adding NPM
Our NPM container is almost just as simple as Composer, but with another new addition. Take a look at the following block that defines the NPM service. Bring your container network down, and add this new service under the Composer one created earlier:
npm:
image: node:latest
container_name: npm
volumes:
- ./src:/var/www/html
working_dir: /var/www/html
entrypoint: ['npm', '--no-bin-links']
networks:
- laravel
We've defined the service as the name of the command we'll be running with it, and just like Composer have built this off of an image available on the Docker Hub (the latest version of Node). Also just like Composer, we've overwritten the default folder structure that npm looks for using the working_dir key and setting it to the application root.
Below that though, is our new option, entrypoint. Like we mentioned earlier, when you run a command with docker-compose run, it runs the command with the same namesake as the service name (npm will run npm, composer will run composer, etc).
But sometimes we need to specify the path to the command, add additional parameters, or even change the command name entirely. This is exactly what entrypoint is used for!
It accepts an array with the first element being the command you'd like to run, and each subsequent items get taken in as flags or parameters that you'd like to set. For our npm service, I had some trouble getting it to run smoothly, so adding the --no-bin-links flag seemed to help that. Using the entrypoint I can easily add this in as an option with a second array value.
If we bring our container network back up with docker-compose up -d, we can run npm commands using the same syntax as earlier:
docker-compose run --rm npm install
docker-compose run --rm npm run dev
The npm container spins up with a Node image, npm install or npm run dev is ran at our application's root, and the output is streamed to our console just like if it was happening on our local machine. Once it's finished the container is brought back down, and our compiled assets are ready to go.
One more to go!
Adding Artisan
In my opinion, this has been the best addition to my workflow for local Laravel development with Docker. Using Artisan commands with Docker ensures that I'll always be able to upgrade my PHP version to match the latest requirements from Laravel, without having to have it installed on my local machine. Additionally, if something really gets stuck, it's just a few seconds to restart the containers vs finding my local PHP process and restarting it (or my computer).
While this isn't going to be built from a Docker Hub image, Artisan runs on PHP, and we already have a working configuration for our PHP service, so we can just use that! Bring your container network down and take a look at the block below which configures our Artisan service. Add it to the bottom of your docker-compose.yml file:
artisan:
build:
context: .
dockerfile: Dockerfile
container_name: artisan
volumes:
- ./src:/var/www/html
depends_on:
- mysql
entrypoint: ['/var/www/html/artisan']
networks:
- laravel
While there's nothing new in here that hasn't been explained already, I'll break it down a little anyway, just for a more thorough description. Instead of using the image: key earlier, we're using build: which takes in a context (the current directory) and a dockerfile that we want to build this container off of. The one in question is the same I've previously used to define our PHP service, and it's incredibly simple.
For the entrypoint, I've had to make an addition. The reason for that, is this: If we were to exclude the entrypoint and run the container using docker-compose run --rm artisan migrate, it would fail because the artisan command isn't installed as a global throughout the container. It's a single file, available in the project's root directory.
By adding in an entrypoint with the full path to the artisan script as the single value in its array, we're basically telling the container to alias /var/www/html/artisan as just artisan.
Let's bring our containers back up a final time with docker-compose up -d --build (since the new artisan container is created with a dockerfile), and test out a few artisan commands:
docker-compose run --rm artisan migrate
docker-compose run --rm artisan key:generate
💥Boom💥
All Set!
It's really that simple to get a much better local Laravel dev environment setup with Docker and docker-compose. I've been tweaking and working with this setup for over half of a year now, and I've absolutely been loving it. I honestly don't ever think that I'll go back to having a locally-installed LAMP stack running on my machine again.
Again, if you want to just check out the source code, you can find it in the GitHub repository here, specifically check out the docker-compose.yml file or clone the repo and add your application's files to the src directory.
Finally, if you have any questions at all or would like help with this, or any other web development-related topics, please feel free to follow me or message me on Twitter.
Thanks for reading!
Top comments (9)
Thank you for this amazing tutorial!
By the way, I came across this bug when trying to build the assets:
sh: 1: cross-env: not foundBy removing the flag
--no-bin-linkswas possible to build the assets again usingdocker-compose run --rm npm run devHello, can anyone help please with this. Having an issue running npm install using this setup. It seems it doesn't like the node-sass dependency and starts spamming something about gyp and compiling stuff. Also the composer container complained about some missing php extensions like gd and gmp so I had to run it directly from the php container instead.
Thanks for this. Awesome!
However when I run composer install, it fails when trying to run artisan command
"post-autoload-dump": [
"Illuminate\Foundation\ComposerScripts::postAutoloadDump",
"@php artisan package:discover --ansi"
],
You have any ideas on how I get the composer container to talk to the php/app container?
When running docker-compose run --rm composer install it shows php version 8 is not compatible while we used version-7.2 in php container.
Also can we access terminal to run all php, artisan and node commands like we run in "laradock workspace".
What does --rm option do?
It destroys the Docker container once it's use has finished up. Otherwise, it will remain active on the system until you bring it down.
Can the
networkpart be removed in compose file for npm and composer? If those are destroyed anyways?There are some really interesting ideas in here. Thanks for sharing this!
I'm going to experiment this setup. Pretty good, just what I was looking for. Thanks!