A Complete Guide to Laravel Sail

⚠️ This content is outdated. It was written just a few days after Laravel Sail’s initial release and Sail has received some updates since then, and more will undoubtedly come. Please visit my blog for an up-to-date version , where this guide was initially published. Thank you. Truman continues to steer his wrecked sailboat towards the infinitely receding horizon. All is calm until we see the bow of the boat suddenly strike a huge, blue wall, knocking Truman off his feet. Truman recovers and clambers across the deck to the bow of the boat. Looming above him out of the sea is a cyclorama of colossal dimensions. The sky he has been sailing towards is nothing but a painted backdrop. (Andrew M. Niccol, ) The Truman Show On December 8 2020, Taylor Otwell announced the launch of , a development environment based on Docker, along with a large overhaul of Laravel's documentation: Laravel Sail The announcement caused a wave of excitement across the community, as a lot of people identified the new environment as a way to finally get into Docker; but it also left some confusion in its wake, as Sail introduces an approach to development that is quite different from its predecessors and isn't exactly a guide to becoming a Docker expert. This post is about what to expect from Laravel Sail, how it works and how to make the most of it; it is also a plea to developers to break away from it, in favour of their own, tailored solution. But before we get there, we need to take a look under the deck, starting with a high-level explanation of what Sail is. What is Laravel Sail? Sail is Laravel's latest development environment. It is the most recent addition to a long list featuring official solutions like and on the one hand, and community efforts like , , and on the other (according to the , Sail is largely inspired by the latter). Homestead Valet Laragon Laradock Takeout Vessel GitHub repository Laravel Sail is based on , a technology leveraging to essentially package up applications so they can run quickly and easily on any operating system. Docker containers The future of Sail appears to be bright, as the Laravel documentation already features it as the to instal and run Laravel projects locally, a spot that Homestead and Valet occupied for years. preferred way How does it compare to its predecessors? As a refresher, Homestead is a box (a virtual machine) pre-packaged with everything most Laravel applications need, including essential components like PHP, MySQL and a web server (Nginx), but also less-often used technologies like PostgreSQL, Redis or Memcached. Vagrant Valet, on the other hand, is a lightweight environment for macOS focused on performance, relying on a local installation of PHP instead of a virtual machine, and intended to be used along with other services like or Takeout to manage other dependencies like databases. DBngin While Homestead and Valet look quite different on paper, they promote the same general approach to local development, which is also shared by most of the aforementioned solutions: they try to be one-size-fits-all environments for Laravel projects and to manage them all under one roof. Sail's approach is different, in that the development environment's description is included with the rest of the codebase. Instead of relying on the presence of a third-party solution on the developer's machine, the project comes with a set of instructions for Docker to pick up and build the corresponding environment. The application comes with batteries included, only requiring a single command to spin up its development environment, regardless of the developer's operating system so long as Docker is installed on it. It also introduces the notion of a bespoke development environment for the application, which, in my opinion, is Laravel Sail's real kicker. While this approach is a major departure from traditional solutions, Sail still bears some resemblance to them around the tools it comes with, some of which are essential, others not. Let's review the most important ones and the way they're implemented. How does it work? From here on, it will be easier to follow along with a fresh installation of Laravel, although the files I refer to come with links to the . If you've got a little bit of time, go follow the now and come back here when you're done. official GitHub repository instructions for your operating system While Sail allows us to we're interested in when creating a new Laravel application, by default it is composed of three main components: PHP, MySQL and Redis. As per the , the whole setup gravitates around two files: (which you will find at the project's root after a fresh installation) and the script (found under ). pick the services documentation docker-compose.yml sail vendor/bin The docker-compose.yml file As mentioned earlier, Laravel Sail is based on Docker, which is a technology leveraging containers. As a rule of thumb, each container should only run one process; roughly translated, that means that each container should only run a single piece of software. If we apply this rule to the above setup, we'll need one container for PHP, another one for MySQL, and a third one for Redis. These containers make up your application, and they need to be for it to function properly. There are several ways to do this, but Laravel Sail relies on to do the job, which is the easiest and most used solution for local setups. orchestrated Docker Compose Docker Compose expects us to describe the various components of our application in a file, in YAML format. If you open the one at the root of the project, you will see a parameter at the top, under which there is a section containing a list of components comprising the ones we've just mentioned: , and . docker-compose.yml version services laravel.test mysql redis I'll describe the and services first, as they are simpler than ; I'll then briefly cover the other, smaller ones that also come by default with a new instal. mysql redis laravel.test The mysql service As the name suggests, the service handles the MySQL database: mysql mysql: image: 'mysql:8.0' ports: - '${FORWARD_DB_PORT:-3306}:3306' environment: MYSQL_ROOT_PASSWORD: '${DB_PASSWORD}' MYSQL_DATABASE: '${DB_DATABASE}' MYSQL_USER: '${DB_USERNAME}' MYSQL_PASSWORD: '${DB_PASSWORD}' MYSQL_ALLOW_EMPTY_PASSWORD: 'yes' volumes: - 'sailmysql:/var/lib/mysql' networks: - sail healthcheck: test: ["CMD", "mysqladmin" , "ping" ] The parameter indicates which should be used for this container. An easy way to understand images and the difference with containers is to borrow from Object-Oriented Programming concepts: an image is akin to a class and a container to an instance of that class. image image Here, we specify that we want to use the tag of the image, corresponding to MySQL version 8.0. By default, images are downloaded from , which is the largest image registry. Have a look at – most images come with simple documentation explaining how to use it. 8.0 mysql Docker Hub the page for MySQL The key allows us to map local ports to container ports, following the format. In the code snippet above, the value of the environment variable (or if that value is empty) is mapped to the container's port. This is mostly useful to connect third-party software to the database, like or ; the setup would also work without it. ports local:container FORWARD_DB_PORT 3306 3306 MySQL Workbench Sequel Ace is for defining environment variables for the container. Here, most of them receive the value of existing environment variables, which are loaded from the file at the root of the project – automatically detects and imports the content of this file. For instance, in the line, the container's environment variable will receive the value of from the file. environments .env docker-compose.yml MYSQL_ROOT_PASSWORD: '${DB_PASSWORD}' MYSQL_ROOT_PASSWORD DB_PASSWORD .env is to declare some of the container's files or folders as , either by mapping specific local files or folders to them or by letting Docker deal with it. volumes volumes Here, a single Docker-managed volume is defined: . This type of volume must be declared in a separate section, at the same level as . We can find it at the bottom of the file: sailmysql volumes services docker-compose.yml volumes: sailmysql: driver: local sailredis: driver: local sailmeilisearch: driver: local The volume is mapped to the container's folder, which is where the MySQL data is stored. This volume ensures that the data is persisted even when the container is destroyed, which is the case when we run the command. sailmysql /var/lib/mysql sail down The section allows us to specify which internal networks the container should be available on. Here, all services are connected to the same network, which is also defined at the bottom of , in the section above the one: networks sail docker-compose.yml networks volumes networks: sail: driver: bridge Finally, is a way to indicate which conditions need to be true for the service to be , as opposed to just be . I'll go back to this soon. healthcheck ready started The redis service The service is very similar to the one: redis mysql redis: image: 'redis:alpine' ports: - '${FORWARD_REDIS_PORT:-6379}:6379' volumes: - 'sailredis:/data' networks: - sail healthcheck: test: ["CMD", "redis-cli" , "ping" ] We pull the tag of the for Redis ( ) and we define which port to forward; we then declare a volume to make the data persistent, connect the container to the network, and define the check to perform in order to consider the service ready. alpine official image Alpine is a lightweight Linux distribution sail The laravel.test service The service is more complex: laravel.test laravel.test: build: context: ./vendor/laravel/sail/runtimes/8.0 dockerfile: Dockerfile args: WWWGROUP: '${WWWGROUP}' image: sail-8.0/app ports: - '${APP_PORT:-80}:80' environment: WWWUSER: '${WWWUSER}' LARAVEL_SAIL: 1 volumes: - '.:/var/www/html' networks: - sail depends_on: - mysql - redis - selenium For starters, the name is a bit confusing, but this service is the one handling PHP (i.e. the one serving the Laravel application). Next, it has a key that we haven't seen before, which points to the that is present under the folder. build Dockerfile vendor/laravel/sail/runtimes/8.0 are text documents containing instructions to build images. Instead of pulling and using an existing image from Docker Hub as-is, the Laravel team chose to describe their own in a Dockerfile. The first time we ran the command, we built that image and created a container based on it. Dockerfiles sail up Open the Dockerfile and take a look at the first line: ubuntu: FROM 20.04 This means that the tag of the is used as a starting point for the custom image; the rest of the file is essentially a list of instructions to build upon it, installing everything a standard Laravel application needs. That includes PHP, various extensions, and other packages like Git or Supervisor, as well as Composer. 20.04 ubuntu image The end of the file also deserves a quick explanation: COPY start-container /usr/ /bin/start-container local COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf COPY php.ini /etc/php/8.0/cli/conf.d/99-sail.ini RUN chmod +x /usr/ /bin/start-container local EXPOSE 8000 ENTRYPOINT [ ] "start-container" We can see that a bunch of local files are copied over to the container: the file is some custom configuration for PHP; php.ini the file is a configuration file for , a process manager here responsible for starting the PHP process; supervisord.conf Supervisor the file is a Bash script that will do a few things every time the container starts, because it is defined as the container's . We can see that it's made executable by the instruction; start-container ENTRYPOINT RUN chmod +x finally, doesn't do anything, apart from informing the reader that this container listens on the specified port at runtime (which actually seems wrong here, since the application is served on port 80, not 8000). EXPOSE 8000 Other things are happening in this Dockerfile, but the above is the gist of it. Note that this one pertains to PHP 8.0, but Laravel Sail also comes with a you can point to from the service in instead. 7.4 version laravel.test docker-compose.yml The service also has a section containing the list of services whose containers should be ready prior to the Laravel application's. Since the latter references both MySQL, Redis and Selenium, theirs should be started and ready first to avoid connection errors. depends_on This is where the health checks described earlier are useful: by default will wait for the specified services to be , which doesn't necessarily mean they are . By specifying on which conditions these services are deemed ready, we ensure they are in the right state prior to starting the Laravel application. depends_on started ready The rest of the settings should be familiar by now, so I'll skip them. The meilisearch, mailhog and selenium services These are the smaller services I referred to earlier; they are already documented , and . The point is they work the same way as the other ones: they pull existing images from Docker Hub and use them as-is, with minimal configuration. here here here The sail script If you followed for your operating system, you must have run the following command at some point: Laravel's installation instructions $ ./vendor/bin/sail up The file that we call here is a Bash script essentially adding a more user-friendly layer on top of sometimes long-winded Docker commands. sail Let's open it now for closer inspection (don't worry if you're not familiar with Bash – it's pretty straightforward). We can ignore the whole first part of the file and focus on the big statement that starts like this: if [ -gt 0 ]; [ -f ./.env ]; ./.env if $# then # Source the ".env" file so Laravel's environment variables are available... if then source fi # ... In plain English, the bit translates to "if the number of arguments is greater than 0", meaning whenever we call the script with arguments, the execution will enter that statement. $# -gt 0 sail if In other words, when we run the command, we call the script with the argument, and the execution gets inside the big statement where it looks for a condition matching the argument. Since there is none, the script goes all the way down to the end of the big , in the sort of catch-all we can find there: ./vendor/bin/sail up sail up if up if else docker-compose # Pass unknown commands to the "docker-compose" binary... else " " $@ fi The comment already describes what's going on – the script passes the argument on to the binary. In other words, when we run we actually run , which is the to start the containers for the services listed in . up docker-compose ./vendor/bin/sail up docker-compose up standard Docker Compose command docker-compose.yml This command downloads the corresponding images first if necessary, and builds the Laravel image based on the Dockerfile as we talked about earlier. Give it a try! Run then – they do the same thing. ./vendor/bin/sail up docker-compose up Let's now look at a more complicated example, one involving Composer, which is among the packages installed by the application's Dockerfile. But before we do that, let's start Sail in to run the containers in the background: detached mode $ ./vendor/bin/sail up -d The script allows us to run Composer commands, e.g.: sail $ ./vendor/bin/sail composer --version The above calls the script with and as arguments, meaning the execution will enter that big statement again. sail composer --version if Let's search for the condition dealing with Composer: [ == ]; 1 [ == ]; docker-compose \ -u sail \ \ composer sail_is_not_running # ... # Proxy Composer commands to the "composer" binary on the application container... elif " " $1 "composer" then shift if " " $EXEC "yes" then exec " " $APP_SERVICE " " $@ else fi # ... The first line of the condition starts with , which is a Bash that skips as many arguments as the number it is followed by. In this case, skips the argument, making the new first argument. The program then makes sure that Sail is running, before executing a weird command split over four lines, which I break down below: shift built-in shift 1 composer --version docker-compose \ -u sail \ \ composer exec " " $APP_SERVICE " " $@ is the way Docker Compose allows us to execute commands on already running containers. is an option indicating which user we want to execute the command as, and is the container on which we want to run it all. Here, its value is , which is the service's name in as explained in a previous section. It is followed by the command we want to run once we're in the container, namely followed by all the script's arguments. These now only comprise , since we've skipped the first argument. exec -u $APP_SERVICE laravel.test docker-compose.yml composer --version In other words, when we run: $ ./vendor/bin/sail composer --version The command that is executed behind the scenes is the following: $ docker-compose -u sail composer exec "laravel.test" "--version" It would be quite cumbersome to type this kind of command every single time; that's why the script provides shortcuts for them, making the user experience much smoother. sail Have a look at the rest of the smaller statements inside the big one to see what else is covered – you'll see that roughly the same principle applies everywhere. if There are a few other features available out of the box (like ), but we've now covered the substance of what Laravel Sail currently offers. While this is a pretty good start already, it is somewhat limited, even for a basic application. making local containers public The good news is that the Laravel team is aware of this, and built the environment with extension in mind: Since Sail is just Docker, you are free to customize nearly everything about it. ( ) The Laravel documentation Let's see what that means in practice. Extending Laravel Sail The code covered in this section is also available as a you can refer to at any moment. GitHub repository We're going to explore three ways to extend Laravel Sail, using as a pretext; but before we proceed, let's make sure we get our hands on as many files as we can. MongoDB The only thing we've got access to initially is the file, but we can publish more assets with the following command, which will create a new folder at the root of the project: docker-compose.yml docker $ ./vendor/bin/sail artisan sail:publish We'll get back to those in a minute; for the time being, let's try and instal the package, which will make it easy to use MongoDB with our favourite framework: Laravel MongoDB $ ./vendor/bin/sail composer require jenssegers/mongodb Unfortunately, Composer is complaining about some missing extension: mongodb/mongodb[dev-master, 1.8.0-RC1, ..., v1.8.x-dev] require ext-mongodb ^1.8.1 -> it is missing from your system. Install or enable PHP's mongodb extension Let's fix this! Installing extra extensions Earlier in this post, we talked about the way Sail uses Dockerfiles to build images matching Laravel's requirements for both PHP 7.4 and PHP 8.0. These files were published with the command we ran at the beginning of this section – all we need to do to add extensions is to edit them and rebuild the corresponding images. Many extensions are available out of the box and we can list them with the following command: $ ./vendor/bin/sail php -m MongoDB is not part of them; to add it, open the file and spot the instruction installing the various packages: docker/8.0/Dockerfile RUN RUN apt-get update \ && apt-get install -y gnupg gosu curl ca-certificates zip unzip git supervisor sqlite3 libcap2-bin \ && mkdir -p ~/.gnupg \ && >> ~/.gnupg/dirmngr.conf \ && apt-key adv --homedir ~/.gnupg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys E5267A6C \ && apt-key adv --homedir ~/.gnupg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C300EE8C \ && > /etc/apt/sources.list.d/ppa_ondrej_php.list \ && apt-get update \ && apt-get install -y php8.0-cli php8.0-dev \ php8.0-pgsql php8.0-sqlite3 php8.0-gd \ php8.0-curl php8.0-memcached \ php8.0-imap php8.0-mysql php8.0-mbstring \ php8.0-xml php8.0-zip php8.0-bcmath php8.0-soap \ php8.0-intl php8.0-readline \ php8.0-msgpack php8.0-igbinary php8.0-ldap \ php8.0-redis \ && php -r | php -- --install-dir=/usr/bin/ --filename=composer \ && curl -sL https://deb.nodesource.com/setup_15.x | bash - \ && apt-get install -y nodejs \ && apt-get -y autoremove \ && apt-get clean \ && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/ echo "disable-ipv6" echo "deb http://ppa.launchpad.net/ondrej/php/ubuntu focal main" "readfile('http://getcomposer.org/installer');" It's easy to identify the block related to PHP extensions since they all start with . Amend the end of the list so it looks like this: php8.0 php8.0-redis php8.0-mongodb \ You can see the detail of the available PHP extensions for Ubuntu 20.04 . here Save the file and run the following command: $ ./vendor/bin/sail build This will go through all the services listed in the file and build the corresponding images if they have changed, including the service's, whose Dockerfile we've just updated. docker-compose.yml laravel.test Once it's done, start the containers again: $ ./vendor/bin/sail up -d The command will detect that the image corresponding to the service has changed, and recreate the container: laravel.test That's it! The MongoDB extension for PHP is now installed and enabled. We've only done it for the PHP 8.0 image, but you can apply the same process to PHP 7.4's by updating the file instead, with as the extension name. docker/7.4/Dockerfile php7.4-mongodb We can now safely import the Laravel package: $ ./vendor/bin/sail composer require jenssegers/mongodb Next up: adding a Docker service for MongoDB. Adding new services MongoDB is essentially another database; as a result, the corresponding service will be very similar to the ones of MySQL and Redis. A quick search on reveals that there is for it, which we are going to use. Docker Hub an official image Its documentation contains an example configuration for Docker Compose, which we can copy and adjust to our needs. Open and add the following service at the bottom, after the other ones: docker-compose.yml mongo: image: 'mongo:4.4' restart: always environment: MONGO_INITDB_ROOT_USERNAME: '${DB_USERNAME}' MONGO_INITDB_ROOT_PASSWORD: '${DB_PASSWORD}' MONGO_INITDB_DATABASE: '${DB_DATABASE}' volumes: - 'sailmongo:/data/db' networks: - sail The changes I've made are the following: first, I specified the tag of the image. If you don't specify one, Docker Compose will pull the tag by default, which is not good practice since it will refer to different versions of MongoDB over time, as new releases are available. The introduction of breaking changes could create instability in your Docker setup, so it's better to target a specific version, matching the production one whenever possible. 4.4 mongo latest Then, I declared a environment variable for the container to create a database with the corresponding name at start-up, and I matched the value of each environment variable to one coming from the file (we'll come back to those in a minute). MONGO_INITDB_DATABASE .env I also added a section, mounting a Docker-managed volume onto the container's folder. The same principle as MySQL and Redis here applies: if you don't persist the data on your local machine, it will be lost every time the MongoDB container is destroyed. In other words, as the MongoDB data is stored in the container's folder, we persist that folder locally using a volume. volumes /data/db /data/db As this volume doesn't exist yet, we need to declare it at the bottom of , after the other ones: docker-compose.yml volumes: sailmysql: driver: local sailredis: driver: local sailmeilisearch: driver: local sailmongo: driver: local Finally, I added the section to ensure the service is on the same network as the others. networks We can now configure Laravel MongoDB as per the package's . Open and add the following database connection: instructions config/database.php => [ => , => env( ), => env( ), => env( ), => env( ), => env( ), => [ => env( , ), ], ], 'mongodb' 'driver' 'mongodb' 'host' 'DB_HOST' 'port' 'DB_PORT' 'database' 'DB_DATABASE' 'username' 'DB_USERNAME' 'password' 'DB_PASSWORD' 'options' 'database' 'DB_AUTHENTICATION_DATABASE' 'admin' Open the file at the root of the project and change the database values as follows: .env DB_CONNECTION=mongodb DB_HOST=mongo DB_PORT=27017 DB_DATABASE=laravel_sail DB_USERNAME=root DB_PASSWORD=root The above makes MongoDB the main database connection; in a real case scenario, you might want to make it a secondary database like Redis, but for demonstration purposes, this will do. is the name of the MongoDB service from ; behind the scenes, Docker Compose resolves the service's name to the container's IP on the networks it manages (in our case, that's the single network defined at the end of ). DB_HOST docker-compose.yml sail docker-compose.yml is the port MongoDB is available on, which is by default, as per the . DB_PORT 27017 image's description We're ready for a test! Run the following command again: $ ./vendor/bin/sail up -d It will download MongoDB's image, create the new volume and start the new container, which will also create the database: laravel_sail Let's make sure of that by running Laravel's default migrations: $ ./vendor/bin/sail artisan migrate We can push the test further by updating the model so it Laravel MongoDB's model: User extends Authenticable \ ; \ \ \ ; \ \ \ \ ; \ \ ; \ \ \ ; { >> \App\Models\User::factory()->create(); Great! Our MongoDB integration is functional. We can keep interacting with it using Tinker and Eloquent, but oftentimes it is useful to have direct access to the database, through third-party software or via a command-line interface such as the . Mongo shell Let's add the latter to our setup. Custom sail commands The good news is the Mongo shell is already available, as long as we know the right formula to summon it. Here it is, along with some extra commands to log into the database and list the users (run the first command from the project's root): MongoDB shell version v4.4.2 connecting to: mongodb://127.0.0.1:27017/?compressors=disabled&gssapiServiceName=mongodb Implicit session: session { "id" : UUID("919072cf-817d-43a6-9ffb-c5e721eeefbc") } MongoDB server version: 4.4.2 Welcome to the MongoDB shell. For interactive help, type "help". For more comprehensive documentation, see https://docs.mongodb.com/ Questions? Try the MongoDB Developer Community Forums https://community.mongodb.com switched to db admin 1 switched to db laravel_sail $ docker-compose mongo mongo exec > use admin > db.auth( , ) "root" "root" > use laravel_sail > db.users.find() The command should look familiar; earlier in the article, we looked at what the script does behind the scenes, which mostly consists of translating simple commands into more complex ones. Here, we're telling the binary to execute the command on the container. docker-compose exec mongo mongo sail sail docker-compose docker-compose mongo mongo To be fair, this command isn't too bad and we could easily remember it; but for consistency, it would be nice to have a simpler equivalent, like the following: sail $ ./vendor/bin/sail mongo To achieve this we'd need to complete the script somehow, but as it is located inside the folder – which is created by Composer – we cannot update it directly. We need a way to build upon it without modifying it, which I've summarised below: sail vendor make a copy of the script at the root of the project; sail replace the content of its big statement with custom conditions; if if none of the custom conditions matches the current arguments, pass them on to the original script. sail If we take a closer look at the file with , we can see that it's a symbolic link to the file: sail ls -al vendor/laravel/sail/bin/sail Let's copy that file to the root of our project now: $ cp vendor/laravel/sail/bin/sail . Open the new copy and replace the content of its big with the following, leaving the rest as-is: if [ -gt 0 ]; [ -f ./.env ]; ./.env [ == ]; [ == ]; docker-compose mongo mongo sail_is_not_running ./vendor/bin/sail if $# then # Source the ".env" file so Laravel's environment variables are available... if then source fi # Initiate a Mongo shell terminal session within the "mongo" container... if " " $1 "mongo" then if " " $EXEC "yes" then exec else fi # Pass unknown commands to the original "sail" script.. else " " $@ fi fi In the above code, we removed all the conditions inside the big and added one of our own, which runs the command we used earlier to access the Mongo shell if the value of the script's first argument is . If it's not, the execution will hit the last statement and call the original script with all the arguments. if...else if mongo else sail You can try this out now – save the file and run the following command: $ ./sail mongo It should open a Mongo shell session in your terminal. Try another command, to make sure the original script is taking over when it's supposed to: sail $ ./sail artisan The Artisan menu should display. That's it! If you need more commands, you can add them as new conditions inside the big of the copy of the script at the root of the project. if...else if sail It works exactly the same way, except that you now need to run instead of (or update your Bash alias if you created one as suggested in the ). ./sail ./vendor/bin/sail documentation We are now running a fully functional instance of MongoDB as part of our Docker setup, nicely integrated with Laravel Sail. But MongoDB is a mere example here – you can do the same with pretty much any technology you'd like to use. Go now! Most major actors have Docker images – official or community-maintained – with easy-to-follow instructions. In most cases, you'll have a local instance of the software running in minutes. take a look There are probably many more things we could do to customise Laravel Sail, but the three methods described above should get you a long way already. At this stage, you may be thinking that Laravel's new environment has a lot going for it, maybe even more so than you initially thought. Yet, the point of this article is to avoid using it... So where am I going with this? What's wrong with Laravel Sail anyway? If you made it this far, you're probably wondering what's wrong with Laravel Sail, now that it's clear how far we can push it. Let me break it to you right now: once you know and understand everything I've explained in the previous sections, you don't need Laravel Sail anymore. That's right – you can take that knowledge and walk away. But before I elaborate on this, let's review some actual pain points of Sail, even though I expect the Laravel team to address most of them sooner rather than later. The first one concerns the custom commands: while it's possible to extend the script as demonstrated earlier, the process is a bit ugly and somewhat hacky. Sail's maintainers could fix this with an explicit Bash extension point allowing users to add their own shortcuts, or by publishing the script along with the other files. sail sail sail Second, the Laravel application is served by PHP's development server. I won't go into too much detail here, but as mentioned before manages the PHP process in the container; is where Supervisor runs the command, which starts PHP's development server under the hood. Supervisor laravel.test this line php artisan serve The point here is that the environment doesn't use a proper web server (e.g. Nginx), which means we can't easily have local domain names, nor bring HTTPS to the setup. This may be fine for quick prototyping, but more elaborate development will most likely need those. The third issue is one I noticed while trying to clone and run a fresh instance of this article's for testing. While the process to create a new Laravel project based on Sail works well, I couldn't find proper instructions to instal and run an existing one. repository You can't run because the folder doesn't exist yet. For this folder to be created, you need to run ; but if your project relies on dependencies present on the Docker image but not on your local machine, won't work. You can run instead, but that doesn't feel right. There should be a way to instal and run an existing project without relying on a local Composer instance and clunky commands. ./vendor/bin/sail up vendor composer install composer install composer install --ignore-platform-reqs The last issue belongs to a separate category, as it relates to Docker overall and not Laravel Sail specifically. It should be carefully considered before going down the Docker road and deserves a section of its own. The whale in the cabin The one major caveat that appears to be absent from the conversation so far relates to performance. While this shouldn't affect Linux users, if you run Docker Desktop on your system you will most likely experience long loading times, especially on macOS (it seems that using on Windows can mitigate the slowness). WSL 2 You can see it for yourself right now: if you're using Docker Desktop and Sail is running, try and load the – you will probably notice a delay. Laravel welcome page I won't go into too much detail here, but the reason essentially comes from the host's underlying filesystem, which does not perform well around mounted local directories. As we've seen, this is how Laravel Sail gets the application's source code in the Laravel application's container, hence the slowness. This is where an approach like Takeout's makes sense, as instead of running PHP from a Docker container, they expect developers to run it on their local machine (e.g. via ), all the while providing instances of services like MySQL or MongoDB, thus offering convenience without sacrificing performance. But from the moment you choose to run PHP via a Docker container (like Sail does), the added value of Takeout decreases, in my opinion. Valet There are strategies to mitigate these performance issues, but the Laravel documentation mentions none of them, let alone the fact that performance might be an issue at all, which I find surprising. That being said, you might be comfortable enough with performance as it is; I, for one, have been OK with it for years, even though I use Docker Desktop on macOS. The bottom line is that this aspect should be carefully considered before moving your whole setup to a solution running PHP in a container, be it Laravel Sail or something else. But once you've made that decision, and whether or not the other issues are eventually addressed, the main idea of this article remains the same. You don't need Laravel Sail If you're considering building anything substantial using Laravel Sail as your development environment, sooner or later you will have to extend it. You'll find yourself fumbling around the Dockerfiles and eventually writing your own; having to add some services to ; and maybe throwing in a few custom Bash commands. docker-compose.yml Once you get there, there's one question you should ask yourself: What's stopping me from building my own setup? The answer is . Once you feel comfortable extending Laravel Sail, you already have the knowledge required to build your own environment. nothing Think about it: the file is not specific to Laravel Sail, that's just how Docker Compose works. The same goes for Dockerfiles – they are standard Docker stuff. The Bash layer? That's all there is to it – some Bash code, and as you can see, it's not that complicated. docker-compose.yml So why artificially restrain yourself within the constraints of Sail? And more importantly: why limit yourself to using Docker in the context of Laravel? Your application may start as a monolith, but it might not always be. Perhaps you've got a separate frontend, and you use Laravel as the API layer. In that case, you might want your development environment to manage them both; to run them simultaneously so they interact with each other like they do on a staging environment or in production. If your whole application is a , your Docker configuration and Bash script could be at the root of the project, and you could have your frontend and backend applications in separate subfolders, e.g. under an folder. monorepo src The corresponding tree view would look something like this: my-app/ ├── bash-script ├── docker-compose.yml └── src/ ├── backend/ │ └── Dockerfile └── frontend/ └── Dockerfile The file would declare two services – one for the backend and one for the frontend – both pointing to each's respective Dockerfile. docker-compose.yml If the backend and the frontend live in different repositories, you could create a third one, containing your Docker development environment exclusively. Just the folder and complete your Bash script so that it pulls both application repositories into it, using the same commands you would normally run by hand. git-ignore src Even if your project is a Laravel monolith, this kind of structure is already cleaner than mixing up development-related files with the rest of the source code. Moreover, if your application grows bigger and needs other components besides Laravel, you're already in a good position to support them. Once you've made the effort to understand Laravel Sail to extend it, nothing is stopping you from building your own development environments, . That's right, you can build bespoke Docker-based environments for anything. whether or not Laravel is part of the equation And if Laravel is part of the stack, nothing prevents you from reusing Sail's Dockerfiles if you're not comfortable writing your own yet; after all, they are already optimised for Laravel. Likewise, you can draw inspiration from Sail's file if that helps. docker-compose.yml Conclusion Don't get me wrong: Laravel Sail has a lot going for it, and I am glad to see such an established actor push forward the adoption of Docker for local development. We love our frameworks because they offer guidelines to achieve desired results in a way we know to be efficient and battle-tested, and it's only natural that they also seek to provide the environment that will allow their users to build upon them. But one thing that Sail incidentally shows us is that this doesn't have to be part of the framework's mandate anymore. Much like Truman's sailboat helps him overcome his fear of the sea and takes him to the edges of the artificial world he lives in, Sail reveals both the confines of Laravel and a way to escape from them. You may feel that Sail is more than enough for your needs today, or that you're not yet ready to go your own way. That's fine. But Laravel will always be limited by its monolithic nature, and as you grow as a developer, the day will come where your Laravel application will be but a single component of a larger system, for which Sail won't be enough anymore. Eventually, your small sailboat will bump into a painted backdrop. If you'd like to explore this further but feel like you need more guidance, I've published that should get you going. It requires no prior knowledge of Docker and covers web servers, HTTPS, domain names and many other things. It doesn't have all the answers but will get you to a place where you can find your own. a series on the subject What you do next is entirely up to you; just know that there's a whole world out there, waiting for you. Truman hesitates. Perhaps he cannot go through with it after all. The camera slowly zooms into Truman's face. _TRUMAN:_ "In case I don't see you – good afternoon, good evening and good night." He steps through the door and is gone. This story was originally published on tech.osteel.me . Resources Laravel Sail documentation Laravel Sail repository This article's repository Docker Hub Docker documentation Overview of Docker Compose Dockerfile reference What is a Container? Docker for local web development series

A Complete Guide to Laravel Sail

Too Long; Didn't Read

Companies Mentioned

@osteel

RELATED STORIES