<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>Laravel 12 on Daniel Zhang</title><link>https://zhangdapeng.dev/tags/laravel-12/</link><description>Recent content in Laravel 12 on Daniel Zhang</description><generator>Hugo -- gohugo.io</generator><language>en-us</language><lastBuildDate>Fri, 20 Nov 2026 15:00:00 +0800</lastBuildDate><atom:link href="https://zhangdapeng.dev/tags/laravel-12/index.xml" rel="self" type="application/rss+xml"/><item><title>Laravel 12 Docker Deployment: Troubleshooting Missing Storage Directories</title><link>https://zhangdapeng.dev/p/laravel-12-docker-storage-directory-missing/</link><pubDate>Fri, 20 Nov 2026 15:00:00 +0800</pubDate><guid>https://zhangdapeng.dev/p/laravel-12-docker-storage-directory-missing/</guid><description>&lt;img src="https://zhangdapeng.dev/p/laravel-12-docker-storage-directory-missing/cover.png" alt="Featured image of post Laravel 12 Docker Deployment: Troubleshooting Missing Storage Directories" /&gt;&lt;h2 id="1-background"&gt;1. Background
&lt;/h2&gt;&lt;p&gt;While working with Laravel projects, I repeatedly encountered a strange issue:&lt;/p&gt;
&lt;p&gt;Some subdirectories under the &lt;code&gt;storage&lt;/code&gt; directory were missing after pulling code from Git or rebuilding and starting Docker containers.&lt;/p&gt;
&lt;p&gt;For example:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;storage/framework/cache/data&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;storage/framework/sessions&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;storage/framework/views&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;storage/app/private&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;storage/app/public&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;storage/logs&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;These directories usually exist when a Laravel project is initialized locally, but they may disappear after deployment.&lt;/p&gt;
&lt;p&gt;When Laravel tries to write cache files, sessions, compiled Blade templates, or application logs, this can result in errors such as:&lt;/p&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;Please provide a valid cache path.
&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;After investigating the issue, I found that it is usually not caused by a Laravel initialization failure. Instead, it is related to how Git handles empty directories and how Docker volume mounts work.&lt;/p&gt;
&lt;h2 id="2-why-doesnt-git-preserve-empty-storage-directories"&gt;2. Why Doesn&amp;rsquo;t Git Preserve Empty Storage Directories?
&lt;/h2&gt;&lt;p&gt;Git does not track empty directories. It only tracks files.&lt;/p&gt;
&lt;p&gt;Many subdirectories inside Laravel&amp;rsquo;s &lt;code&gt;storage&lt;/code&gt; directory are initially empty. They are intended to store runtime-generated files such as caches, logs, sessions, and temporary data.&lt;/p&gt;
&lt;p&gt;If a directory does not contain any tracked files, Git will not include it in the repository.&lt;/p&gt;
&lt;p&gt;For example:&lt;/p&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;storage/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── app/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ ├── private/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ └── public/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── framework/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ ├── cache/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ │ └── data/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ ├── sessions/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ └── views/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;└── logs/
&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;If these directories are empty, Git will not preserve their structure when committing the project.&lt;/p&gt;
&lt;p&gt;As a result, some required directories may be missing after running &lt;code&gt;git clone&lt;/code&gt; or &lt;code&gt;git pull&lt;/code&gt; on a server.&lt;/p&gt;
&lt;h3 id="solution-use-gitignore-files-to-preserve-empty-directories"&gt;Solution: Use .gitignore Files to Preserve Empty Directories
&lt;/h3&gt;&lt;p&gt;The recommended approach is to place a &lt;code&gt;.gitignore&lt;/code&gt; file inside each directory that needs to be preserved.&lt;/p&gt;
&lt;p&gt;For example:&lt;/p&gt;
&lt;pre tabindex="0"&gt;&lt;code class="language-gitignore" data-lang="gitignore"&gt;*
!.gitignore
&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;This configuration means:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;*&lt;/code&gt;: Ignore all files and subdirectories in the current directory.&lt;/li&gt;
&lt;li&gt;&lt;code&gt;!.gitignore&lt;/code&gt;: Explicitly keep the &lt;code&gt;.gitignore&lt;/code&gt; file itself.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This allows Git to preserve the directory structure without committing runtime-generated files.&lt;/p&gt;
&lt;h2 id="3-recommended-storage-directory-structure-for-laravel-12"&gt;3. Recommended Storage Directory Structure for Laravel 12
&lt;/h2&gt;&lt;p&gt;For a typical Laravel 12 application, the following directory structure should be preserved:&lt;/p&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;storage/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── app/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ ├── .gitignore
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ ├── private/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ │ └── .gitignore
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ └── public/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ └── .gitignore
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── framework/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ ├── cache/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ │ ├── .gitignore
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ │ └── data/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ │ └── .gitignore
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ ├── sessions/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ │ └── .gitignore
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ └── views/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ └── .gitignore
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;└── logs/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; └── .gitignore
&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;Different directories require slightly different ignore rules.&lt;/p&gt;
&lt;h3 id="31-storageappgitignore"&gt;3.1 storage/app/.gitignore
&lt;/h3&gt;&lt;pre tabindex="0"&gt;&lt;code class="language-gitignore" data-lang="gitignore"&gt;*
!private/
!public/
!.gitignore
&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;This preserves the &lt;code&gt;private&lt;/code&gt; and &lt;code&gt;public&lt;/code&gt; directories while ignoring their contents.&lt;/p&gt;
&lt;h3 id="32-storageframeworkcachegitignore"&gt;3.2 storage/framework/cache/.gitignore
&lt;/h3&gt;&lt;pre tabindex="0"&gt;&lt;code class="language-gitignore" data-lang="gitignore"&gt;*
!data/
!.gitignore
&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;This ensures that the &lt;code&gt;data&lt;/code&gt; directory remains in the repository.&lt;/p&gt;
&lt;h3 id="33-other-runtime-directories"&gt;3.3 Other Runtime Directories
&lt;/h3&gt;&lt;p&gt;Create a &lt;code&gt;.gitignore&lt;/code&gt; file in each of the following directories:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;storage/app/private/&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;storage/app/public/&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;storage/framework/cache/data/&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;storage/framework/sessions/&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;storage/framework/views/&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;storage/logs/&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Use the following content:&lt;/p&gt;
&lt;pre tabindex="0"&gt;&lt;code class="language-gitignore" data-lang="gitignore"&gt;*
!.gitignore
&lt;/code&gt;&lt;/pre&gt;&lt;h3 id="34-create-everything-with-one-command"&gt;3.4 Create Everything with One Command
&lt;/h3&gt;&lt;p&gt;Run the following commands from your Laravel project root:&lt;/p&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-bash" data-lang="bash"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;mkdir -p storage/app/private &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; storage/app/public &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; storage/framework/cache/data &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; storage/framework/sessions &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; storage/framework/views &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; storage/logs
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nb"&gt;printf&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;*\n!private/\n!public/\n!.gitignore\n&amp;#34;&lt;/span&gt; &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &amp;gt; storage/app/.gitignore
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nb"&gt;printf&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;*\n!data/\n!.gitignore\n&amp;#34;&lt;/span&gt; &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &amp;gt; storage/framework/cache/.gitignore
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nb"&gt;printf&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;*\n!.gitignore\n&amp;#34;&lt;/span&gt; &lt;span class="p"&gt;|&lt;/span&gt; tee &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; storage/app/private/.gitignore &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; storage/app/public/.gitignore &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; storage/framework/cache/data/.gitignore &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; storage/framework/sessions/.gitignore &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; storage/framework/views/.gitignore &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; storage/logs/.gitignore &amp;gt; /dev/null
&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;After creating these files, check whether Git recognizes them:&lt;/p&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-bash" data-lang="bash"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;git status --short
&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;If some files are still ignored because of global Git ignore rules, you can force-add them:&lt;/p&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-bash" data-lang="bash"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;git add -f storage/app/.gitignore
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;git add -f storage/app/private/.gitignore
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;git add -f storage/app/public/.gitignore
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;git add -f storage/framework/cache/.gitignore
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;git add -f storage/framework/cache/data/.gitignore
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;git add -f storage/framework/sessions/.gitignore
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;git add -f storage/framework/views/.gitignore
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;git add -f storage/logs/.gitignore
&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;Note that force-adding only addresses the immediate issue. You should still inspect your global Git ignore configuration to avoid unintentionally ignoring other project files.&lt;/p&gt;
&lt;h2 id="4-docker-volume-mounts-can-hide-existing-directories"&gt;4. Docker Volume Mounts Can Hide Existing Directories
&lt;/h2&gt;&lt;p&gt;This is another important issue to consider when deploying Laravel with Docker.&lt;/p&gt;
&lt;p&gt;For example, your &lt;code&gt;docker-compose.yml&lt;/code&gt; might contain:&lt;/p&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;app&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;./storage:/var/www/html/storage&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;This is a Docker Bind Mount.&lt;/p&gt;
&lt;p&gt;Docker mounts the host&amp;rsquo;s &lt;code&gt;./storage&lt;/code&gt; directory into the container at &lt;code&gt;/var/www/html/storage&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;The important detail is:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;A bind mount hides the existing contents of the corresponding directory inside the container. It does not automatically merge the host directory with the container directory.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Consider the following scenario:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Your Dockerfile copies the complete Laravel project into the image.&lt;/li&gt;
&lt;li&gt;The image originally contains a complete &lt;code&gt;storage&lt;/code&gt; directory.&lt;/li&gt;
&lt;li&gt;However, the host&amp;rsquo;s &lt;code&gt;./storage&lt;/code&gt; directory is empty or missing some subdirectories.&lt;/li&gt;
&lt;li&gt;When the container starts, the bind mount hides the original &lt;code&gt;storage&lt;/code&gt; directory contents inside the image.&lt;/li&gt;
&lt;li&gt;Laravel sees the incomplete directory structure from the host instead.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;This explains why a Docker image can be built successfully but still encounter missing directories after the container starts.&lt;/p&gt;
&lt;h3 id="how-to-verify-whether-a-volume-mount-is-the-cause"&gt;How to Verify Whether a Volume Mount Is the Cause
&lt;/h3&gt;&lt;p&gt;First, inspect the resolved Docker Compose configuration:&lt;/p&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-bash" data-lang="bash"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;docker compose config
&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;Then inspect the actual container mounts:&lt;/p&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-bash" data-lang="bash"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;docker inspect &amp;lt;container_name&amp;gt;
&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;You can also enter the running container and check the directory structure:&lt;/p&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-bash" data-lang="bash"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; app ls -la storage/framework
&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;If the directories exist in the image but disappear after the container starts, investigate the volume mount configuration first.&lt;/p&gt;
&lt;h2 id="5-add-a-startup-fallback-for-docker-deployments"&gt;5. Add a Startup Fallback for Docker Deployments
&lt;/h2&gt;&lt;p&gt;Besides preserving directories through Git, I recommend automatically checking and creating the required directories whenever the Docker container starts.&lt;/p&gt;
&lt;p&gt;Create a file named &lt;code&gt;docker/entrypoint.sh&lt;/code&gt;:&lt;/p&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-bash" data-lang="bash"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="cp"&gt;#!/bin/sh
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nb"&gt;set&lt;/span&gt; -e
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="c1"&gt;# Create required Laravel storage directories&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;mkdir -p /var/www/html/storage/app/private &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; /var/www/html/storage/app/public &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; /var/www/html/storage/framework/cache/data &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; /var/www/html/storage/framework/sessions &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; /var/www/html/storage/framework/views &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; /var/www/html/storage/logs
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="c1"&gt;# Fix directory ownership&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;chown -R www-data:www-data &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; /var/www/html/storage &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; /var/www/html/bootstrap/cache
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="c1"&gt;# Set appropriate permissions&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;chmod -R &lt;span class="m"&gt;775&lt;/span&gt; &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; /var/www/html/storage &lt;span class="se"&gt;\
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; /var/www/html/bootstrap/cache
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="c1"&gt;# Execute the original container command&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nb"&gt;exec&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;&lt;/span&gt;&lt;span class="nv"&gt;$@&lt;/span&gt;&lt;span class="s2"&gt;&amp;#34;&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;Then configure your Dockerfile:&lt;/p&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-dockerfile" data-lang="dockerfile"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="k"&gt;COPY&lt;/span&gt; docker/entrypoint.sh /usr/local/bin/entrypoint.sh&lt;span class="err"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="err"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="k"&gt;RUN&lt;/span&gt; chmod +x /usr/local/bin/entrypoint.sh&lt;span class="err"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="err"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="k"&gt;ENTRYPOINT&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;&amp;#34;/usr/local/bin/entrypoint.sh&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="err"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="err"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="k"&gt;CMD&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;&amp;#34;php-fpm&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="err"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;Now, whenever the container starts, the entrypoint script will automatically check and recreate the required directories.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Important considerations:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The example assumes your Laravel application is located at &lt;code&gt;/var/www/html&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;It assumes PHP-FPM runs as the &lt;code&gt;www-data&lt;/code&gt; user.&lt;/li&gt;
&lt;li&gt;If you use Alpine-based images or a custom runtime user, adjust the user and group accordingly.&lt;/li&gt;
&lt;li&gt;If your container uses a read-only filesystem, you must configure writable directories separately.&lt;/li&gt;
&lt;li&gt;For production environments with large persistent directories, avoid recursively changing ownership on every startup. Set the initial permissions during image construction whenever possible.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id="6-additional-considerations-for-docker-deployments"&gt;6. Additional Considerations for Docker Deployments
&lt;/h2&gt;&lt;h3 id="61-avoid-mounting-the-entire-storage-directory-without-a-specific-reason"&gt;6.1 Avoid Mounting the Entire Storage Directory Without a Specific Reason
&lt;/h3&gt;&lt;p&gt;You do not necessarily need to mount the entire &lt;code&gt;storage&lt;/code&gt; directory to the host.&lt;/p&gt;
&lt;p&gt;If you only need to persist uploaded public files, you can mount that specific directory instead:&lt;/p&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;app&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;./storage/app/public:/var/www/html/storage/app/public&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;However, determine whether uploaded files, logs, caches, and other runtime data need persistence based on your deployment architecture.&lt;/p&gt;
&lt;h3 id="62-understand-docker-volume-initialization"&gt;6.2 Understand Docker Volume Initialization
&lt;/h3&gt;&lt;p&gt;Named volumes behave somewhat differently from bind mounts.&lt;/p&gt;
&lt;p&gt;For example:&lt;/p&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;storage_data:/var/www/html/storage&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;When Docker mounts a new, empty named volume over a non-empty directory in the container, it normally copies the existing contents into the volume.&lt;/p&gt;
&lt;p&gt;However, this does not mean Docker automatically synchronizes directory structures every time the container starts.&lt;/p&gt;
&lt;p&gt;Once the volume has been initialized, changes to the corresponding directory in a newly built image are not automatically merged into the existing volume.&lt;/p&gt;
&lt;h3 id="63-check-directory-permissions"&gt;6.3 Check Directory Permissions
&lt;/h3&gt;&lt;p&gt;Laravel needs write permissions for the following directories:&lt;/p&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;storage/
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;bootstrap/cache/
&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;Check their permissions inside the container:&lt;/p&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-bash" data-lang="bash"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;ls -ld storage bootstrap/cache
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;ls -la storage/framework
&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;If necessary, fix them:&lt;/p&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-bash" data-lang="bash"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;chown -R www-data:www-data storage bootstrap/cache
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;chmod -R &lt;span class="m"&gt;775&lt;/span&gt; storage bootstrap/cache
&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;Avoid using &lt;code&gt;chmod -R 777&lt;/code&gt; as a quick fix. Production environments should follow the principle of least privilege.&lt;/p&gt;
&lt;h2 id="7-lessons-learned"&gt;7. Lessons Learned
&lt;/h2&gt;&lt;p&gt;This issue reminded me that maintaining a Laravel project&amp;rsquo;s directory structure is not just a framework initialization concern. It also involves Git version control and Docker deployment behavior.&lt;/p&gt;
&lt;p&gt;Here are the key takeaways:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Git does not track empty directories.&lt;/strong&gt; Use directory-level &lt;code&gt;.gitignore&lt;/code&gt; files to preserve the required Laravel directory structure.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Runtime files should not be committed.&lt;/strong&gt; Cache files, sessions, logs, and temporary files should remain excluded from Git.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Docker volumes can hide existing container directories.&lt;/strong&gt; In particular, bind mounts can make a complete directory inside an image appear incomplete when the host directory is missing files.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Startup scripts should be resilient.&lt;/strong&gt; Use &lt;code&gt;mkdir -p&lt;/code&gt; to recreate required directories and reduce deployment-related issues.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Directory permissions matter.&lt;/strong&gt; Ensure the PHP runtime user has appropriate write permissions for &lt;code&gt;storage&lt;/code&gt; and &lt;code&gt;bootstrap/cache&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id="final-recommendations"&gt;Final Recommendations
&lt;/h3&gt;&lt;p&gt;For Laravel projects deployed with Docker, I recommend combining the following approaches:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Git:&lt;/strong&gt; Use directory-level &lt;code&gt;.gitignore&lt;/code&gt; files to preserve required empty directories.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Dockerfile:&lt;/strong&gt; Create the required directories and configure initial permissions during image construction.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Entrypoint:&lt;/strong&gt; Use &lt;code&gt;mkdir -p&lt;/code&gt; as a fallback whenever the container starts.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Docker Compose:&lt;/strong&gt; Design volume mounts carefully and avoid unnecessary directory overrides.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;By addressing these concerns at the source-control, image-build, and container-startup levels, you can prevent missing &lt;code&gt;storage&lt;/code&gt; directories and avoid repeatedly troubleshooting the same issue across Laravel deployments.&lt;/p&gt;</description></item></channel></rss>