1. Background
While working with Laravel projects, I repeatedly encountered a strange issue:
Some subdirectories under the storage directory were missing after pulling code from Git or rebuilding and starting Docker containers.
For example:
storage/framework/cache/datastorage/framework/sessionsstorage/framework/viewsstorage/app/privatestorage/app/publicstorage/logs
These directories usually exist when a Laravel project is initialized locally, but they may disappear after deployment.
When Laravel tries to write cache files, sessions, compiled Blade templates, or application logs, this can result in errors such as:
Please provide a valid cache path.
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.
2. Why Doesn’t Git Preserve Empty Storage Directories?
Git does not track empty directories. It only tracks files.
Many subdirectories inside Laravel’s storage directory are initially empty. They are intended to store runtime-generated files such as caches, logs, sessions, and temporary data.
If a directory does not contain any tracked files, Git will not include it in the repository.
For example:
storage/
├── app/
│ ├── private/
│ └── public/
├── framework/
│ ├── cache/
│ │ └── data/
│ ├── sessions/
│ └── views/
└── logs/
If these directories are empty, Git will not preserve their structure when committing the project.
As a result, some required directories may be missing after running git clone or git pull on a server.
Solution: Use .gitignore Files to Preserve Empty Directories
The recommended approach is to place a .gitignore file inside each directory that needs to be preserved.
For example:
*
!.gitignore
This configuration means:
*: Ignore all files and subdirectories in the current directory.!.gitignore: Explicitly keep the.gitignorefile itself.
This allows Git to preserve the directory structure without committing runtime-generated files.
3. Recommended Storage Directory Structure for Laravel 12
For a typical Laravel 12 application, the following directory structure should be preserved:
storage/
├── app/
│ ├── .gitignore
│ ├── private/
│ │ └── .gitignore
│ └── public/
│ └── .gitignore
├── framework/
│ ├── cache/
│ │ ├── .gitignore
│ │ └── data/
│ │ └── .gitignore
│ ├── sessions/
│ │ └── .gitignore
│ └── views/
│ └── .gitignore
└── logs/
└── .gitignore
Different directories require slightly different ignore rules.
3.1 storage/app/.gitignore
*
!private/
!public/
!.gitignore
This preserves the private and public directories while ignoring their contents.
3.2 storage/framework/cache/.gitignore
*
!data/
!.gitignore
This ensures that the data directory remains in the repository.
3.3 Other Runtime Directories
Create a .gitignore file in each of the following directories:
storage/app/private/storage/app/public/storage/framework/cache/data/storage/framework/sessions/storage/framework/views/storage/logs/
Use the following content:
*
!.gitignore
3.4 Create Everything with One Command
Run the following commands from your Laravel project root:
mkdir -p storage/app/private \
storage/app/public \
storage/framework/cache/data \
storage/framework/sessions \
storage/framework/views \
storage/logs
printf "*\n!private/\n!public/\n!.gitignore\n" \
> storage/app/.gitignore
printf "*\n!data/\n!.gitignore\n" \
> storage/framework/cache/.gitignore
printf "*\n!.gitignore\n" | tee \
storage/app/private/.gitignore \
storage/app/public/.gitignore \
storage/framework/cache/data/.gitignore \
storage/framework/sessions/.gitignore \
storage/framework/views/.gitignore \
storage/logs/.gitignore > /dev/null
After creating these files, check whether Git recognizes them:
git status --short
If some files are still ignored because of global Git ignore rules, you can force-add them:
git add -f storage/app/.gitignore
git add -f storage/app/private/.gitignore
git add -f storage/app/public/.gitignore
git add -f storage/framework/cache/.gitignore
git add -f storage/framework/cache/data/.gitignore
git add -f storage/framework/sessions/.gitignore
git add -f storage/framework/views/.gitignore
git add -f storage/logs/.gitignore
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.
4. Docker Volume Mounts Can Hide Existing Directories
This is another important issue to consider when deploying Laravel with Docker.
For example, your docker-compose.yml might contain:
services:
app:
volumes:
- ./storage:/var/www/html/storage
This is a Docker Bind Mount.
Docker mounts the host’s ./storage directory into the container at /var/www/html/storage.
The important detail is:
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.
Consider the following scenario:
- Your Dockerfile copies the complete Laravel project into the image.
- The image originally contains a complete
storagedirectory. - However, the host’s
./storagedirectory is empty or missing some subdirectories. - When the container starts, the bind mount hides the original
storagedirectory contents inside the image. - Laravel sees the incomplete directory structure from the host instead.
This explains why a Docker image can be built successfully but still encounter missing directories after the container starts.
How to Verify Whether a Volume Mount Is the Cause
First, inspect the resolved Docker Compose configuration:
docker compose config
Then inspect the actual container mounts:
docker inspect <container_name>
You can also enter the running container and check the directory structure:
docker compose exec app ls -la storage/framework
If the directories exist in the image but disappear after the container starts, investigate the volume mount configuration first.
5. Add a Startup Fallback for Docker Deployments
Besides preserving directories through Git, I recommend automatically checking and creating the required directories whenever the Docker container starts.
Create a file named docker/entrypoint.sh:
#!/bin/sh
set -e
# Create required Laravel storage directories
mkdir -p /var/www/html/storage/app/private \
/var/www/html/storage/app/public \
/var/www/html/storage/framework/cache/data \
/var/www/html/storage/framework/sessions \
/var/www/html/storage/framework/views \
/var/www/html/storage/logs
# Fix directory ownership
chown -R www-data:www-data \
/var/www/html/storage \
/var/www/html/bootstrap/cache
# Set appropriate permissions
chmod -R 775 \
/var/www/html/storage \
/var/www/html/bootstrap/cache
# Execute the original container command
exec "$@"
Then configure your Dockerfile:
COPY docker/entrypoint.sh /usr/local/bin/entrypoint.sh
RUN chmod +x /usr/local/bin/entrypoint.sh
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
CMD ["php-fpm"]
Now, whenever the container starts, the entrypoint script will automatically check and recreate the required directories.
Important considerations:
- The example assumes your Laravel application is located at
/var/www/html. - It assumes PHP-FPM runs as the
www-datauser. - If you use Alpine-based images or a custom runtime user, adjust the user and group accordingly.
- If your container uses a read-only filesystem, you must configure writable directories separately.
- For production environments with large persistent directories, avoid recursively changing ownership on every startup. Set the initial permissions during image construction whenever possible.
6. Additional Considerations for Docker Deployments
6.1 Avoid Mounting the Entire Storage Directory Without a Specific Reason
You do not necessarily need to mount the entire storage directory to the host.
If you only need to persist uploaded public files, you can mount that specific directory instead:
services:
app:
volumes:
- ./storage/app/public:/var/www/html/storage/app/public
However, determine whether uploaded files, logs, caches, and other runtime data need persistence based on your deployment architecture.
6.2 Understand Docker Volume Initialization
Named volumes behave somewhat differently from bind mounts.
For example:
volumes:
- storage_data:/var/www/html/storage
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.
However, this does not mean Docker automatically synchronizes directory structures every time the container starts.
Once the volume has been initialized, changes to the corresponding directory in a newly built image are not automatically merged into the existing volume.
6.3 Check Directory Permissions
Laravel needs write permissions for the following directories:
storage/
bootstrap/cache/
Check their permissions inside the container:
ls -ld storage bootstrap/cache
ls -la storage/framework
If necessary, fix them:
chown -R www-data:www-data storage bootstrap/cache
chmod -R 775 storage bootstrap/cache
Avoid using chmod -R 777 as a quick fix. Production environments should follow the principle of least privilege.
7. Lessons Learned
This issue reminded me that maintaining a Laravel project’s directory structure is not just a framework initialization concern. It also involves Git version control and Docker deployment behavior.
Here are the key takeaways:
- Git does not track empty directories. Use directory-level
.gitignorefiles to preserve the required Laravel directory structure. - Runtime files should not be committed. Cache files, sessions, logs, and temporary files should remain excluded from Git.
- Docker volumes can hide existing container directories. In particular, bind mounts can make a complete directory inside an image appear incomplete when the host directory is missing files.
- Startup scripts should be resilient. Use
mkdir -pto recreate required directories and reduce deployment-related issues. - Directory permissions matter. Ensure the PHP runtime user has appropriate write permissions for
storageandbootstrap/cache.
Final Recommendations
For Laravel projects deployed with Docker, I recommend combining the following approaches:
- Git: Use directory-level
.gitignorefiles to preserve required empty directories. - Dockerfile: Create the required directories and configure initial permissions during image construction.
- Entrypoint: Use
mkdir -pas a fallback whenever the container starts. - Docker Compose: Design volume mounts carefully and avoid unnecessary directory overrides.
By addressing these concerns at the source-control, image-build, and container-startup levels, you can prevent missing storage directories and avoid repeatedly troubleshooting the same issue across Laravel deployments.
