README

A complete Docker setup for Laravel applications with PostgreSQL database, Nginx web server, and PHP-FPM. This package provides an easy-to-use environment for developing and deploying Laravel applications.

Features

• PHP 8.3 with essential extensions for Laravel
• PostgreSQL 16 database
• Nginx web server with optimized configuration
• Composer for dependency management
• Automatic port detection to avoid conflicts
• Production deployment scripts
• Database synchronization tools
• Permission management for Laravel storage

Installation

Via Composer

composer require malickteuwdev/docker-for-laravel --dev

Or add it manually to your composer.json:

{
    "require-dev": {
        "malickteuwdev/docker-for-laravel": "^1.0"
    }
}

Then run:

composer install

Manual Installation

If you prefer manual installation, you can download the package and copy the docker/ directory and docker-compose.yml file into your Laravel project root.

Prerequisites

Before using this Docker setup, ensure you have the following installed on your system:

• Docker (version 20.10 or later)
• Docker Compose (version 2.0 or later)
• A Laravel project with artisan file in the root directory

Quick Start

1. Install the package via Composer (see Installation section above)

2. Initialize the environment:

   php artisan docker:init

   Or if you prefer using the script directly:

   bash vendor/your-vendor/docker-for-laravel/docker/scripts/init.sh

   This script will:

   • Detect your Laravel project
   • Create/update the .env file with necessary variables
   • Detect a free port for the application
   • Build and start the Docker containers
   • Set proper permissions for Laravel storage

3. Access your application: Open your browser and navigate to http://localhost:{APP_PORT} (default: 8080)

Configuration

Environment Variables

The setup uses the following environment variables (configured automatically in .env):

• APP_PORT: Port for the web application (auto-detected)
• PROJECT_NAME: Name of your project (defaults to directory name)
• DB_CONNECTION: Database connection (set to pgsql)
• DB_HOST: Database host (set to db)
• DB_PORT: Database port (5432)
• DB_DATABASE: Database name
• DB_USERNAME: Database username
• DB_PASSWORD: Database password
• CONTAINER_SUFFIX: Unique suffix for container names

Customizing PHP Version

composer create-project laravel/laravel projet-laravel10 "10.*"

To use a different PHP version, modify the ARG PHP_VERSION in docker/php/Dockerfile:

ARG PHP_VERSION=8.2  # or 8.1, 8.0, etc.

Nginx Configuration

The Nginx configuration is in docker/nginx/default.conf.template. It includes:

• PHP-FPM upstream to the app container
• Optimized settings for Laravel
• Security headers (htaccess protection)

Usage

Starting the Application

php artisan docker:start

Or using the script directly:

bash vendor/malickteuwdev/docker-for-laravel/docker/scripts/init.sh

Stopping the Application

php artisan docker:stop

Or:

docker compose down

Rebuilding Containers

php artisan docker:rebuild

Or:

docker compose up -d --build

Accessing Containers

# PHP container
php artisan docker:shell

# Database container
php artisan docker:db-shell

Or manually:

# PHP container
docker exec -it {PROJECT_NAME}_{CONTAINER_SUFFIX}_app bash

# Database container
docker exec -it {PROJECT_NAME}_{CONTAINER_SUFFIX}_db psql -U {DB_USERNAME} -d {DB_DATABASE}

Laravel Artisan Commands

php artisan docker:artisan migrate
php artisan docker:artisan cache:clear

Or directly:

docker exec {PROJECT_NAME}_{CONTAINER_SUFFIX}_app php artisan migrate
docker exec {PROJECT_NAME}_{CONTAINER_SUFFIX}_app php artisan cache:clear

Production Deployment

For production deployment, use the provided script:

php artisan docker:deploy-prod

Or using the script directly:

bash vendor/malickteuwdev/docker-for-laravel/docker/scripts/deploy_prod.sh

This script will:

1. Create a .env.production file with production settings
2. Prompt for production database credentials
3. Dump your local database
4. Push the dump to the production database

⚠️ Warning: This will overwrite the production database. Make sure to backup your data first.

Database Synchronization

The database sync tool allows you to synchronize databases between local and remote environments:

php artisan docker:sync-db

Or using the script directly:

bash vendor/malickteuwdev/docker-for-laravel/docker/scripts/sync_db.sh

Choose between:

• push: Send local database to remote
• pull: Get remote database to local

The script includes safety features like optional remote backups before overwriting.

Laravel Integration

This package includes Laravel service provider integration for easier management:

Service Provider

The package registers a service provider that adds the following Artisan commands:

• php artisan docker:init - Initialize Docker environment
• php artisan docker:start - Start Docker containers
• php artisan docker:stop - Stop Docker containers
• php artisan docker:rebuild - Rebuild Docker containers
• php artisan docker:shell - Access PHP container shell
• php artisan docker:db-shell - Access database shell
• php artisan docker:artisan {command} - Run Laravel artisan commands in container
• php artisan docker:deploy-prod - Deploy to production
• php artisan docker:sync-db - Synchronize databases

Publishing Assets

To publish the Docker configuration files to your project:

php artisan vendor:publish --provider="MalickTeuwDev\DockerForLaravel\DockerForLaravelServiceProvider"

This will copy the Docker files to your project's root directory.

Project Structure

After publishing/installation, your project will have:

your-laravel-project/
├── docker/
│   ├── docker_for_laravel/     # (empty directory for potential future use)
│   ├── nginx/
│   │   └── default.conf.template  # Nginx configuration template
│   ├── php/
│   │   └── Dockerfile            # PHP-FPM container definition
│   └── scripts/
│       ├── init.sh              # Main initialization script
│       ├── setup_env.sh         # Environment setup
│       ├── entrypoint.sh        # Container entrypoint
│       ├── deploy_prod.sh       # Production deployment
│       ├── sync_db.sh           # Database sync
│       ├── helpers.sh           # Utility functions
│       └── detect_free_port.sh  # Port detection
├── docker-compose.yml           # Docker Compose configuration
└── vendor/
    └── your-vendor/
        └── docker-for-laravel/  # Package source

Troubleshooting

Common Issues

1. Port already in use:

   • The setup automatically detects free ports
   • Check APP_PORT in your .env file

2. Permission issues:

   • The init script sets proper permissions automatically
   • If issues persist, run:

     docker exec {CONTAINER_NAME}_app chown -R www-data:www-data storage bootstrap/cache

3. Database connection failed:

   • Ensure containers are running: docker compose ps
   • Check database logs: docker compose logs db
   • Verify .env database settings

4. Composer install fails:

   • Check PHP version compatibility
   • Ensure proper file permissions

Logs

View logs for all services:

docker compose logs

View logs for specific service:

docker compose logs app
docker compose logs db
docker compose logs nginx

Cleanup

To completely reset the environment:

docker compose down --volumes --remove-orphans
docker system prune -f

Versioning

This package follows Semantic Versioning.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Testing

composer test

Changelog

See CHANGELOG for recent changes.

Credits

• Laravel - The PHP framework
• Docker - Container platform
• PostgreSQL - Database system

License

This package is open-sourced software licensed under the MIT license.