Download the PHP package mwguerra/docker-local without Composer

docker-local

Complete Docker development environment for Laravel with a powerful CLI.

Global Composer Package — Install once, use everywhere. No per-project Docker configuration needed.

Quick Install

For experienced developers — get up and running in 60 seconds:

Need prerequisites first? See Installation for platform-specific setup guides.

Features

• PHP 8.4 with Xdebug 3.4, FFmpeg, and all Laravel extensions
• MySQL 9.1 and PostgreSQL 17 with pgvector (AI embeddings)
• Redis 8 for cache, sessions, and queues
• MinIO S3-compatible object storage
• Traefik 3.6 reverse proxy with automatic SSL
• Mailpit for email testing
• RTMP Server (optional) for live streaming with HLS
• Whisper AI (optional) for audio transcription
• Node.js 20 (optional) standalone container for asset builds
• 50+ CLI commands for rapid development
• Multi-project support with automatic isolation
• Cross-platform - Linux, macOS, and Windows (WSL2)

Table of Contents

• Quick Install
• Requirements
• Installation
  • Linux
  • macOS
  • Windows (WSL2)
• Quick Start
  • New Project
  • Existing Project
• CLI Commands
• Configuration
  • Directory Structure
  • Package Structure (Source Code)
  • User Configuration
  • Projects Directory
  • Understanding Environment Files
• Services
• Optional Services
• Multi-Project Support
  • What Gets Created Automatically
  • Automatic Isolation Details
  • Redis Database Allocation
  • Running Multiple Projects Simultaneously
• Migrating from Project-Specific Docker
• IDE Integration
• Troubleshooting
• Contributing
• License

Requirements

All Platforms

System Requirements

• RAM: 8GB minimum, 16GB recommended
• Disk: 20GB free space
• CPU: 64-bit processor with virtualization support

Installation

Linux

Tested on Ubuntu 22.04+, Debian 12+, Fedora 38+, and Arch Linux.

macOS

Tested on macOS 12 (Monterey) and later.

Windows (WSL2)

Important: docker-local requires WSL2 on Windows. Native Windows is not supported.

Step 1: Install WSL2

Restart your computer when prompted.

Step 2: Install Docker Desktop

1. Download Docker Desktop for Windows
2. During installation, ensure "Use WSL 2 based engine" is checked
3. After installation, go to Settings > Resources > WSL Integration
4. Enable integration with your Ubuntu distribution

Step 3: Install docker-local (in WSL2 Ubuntu)

Accessing Projects from Windows

Your WSL2 projects are accessible in Windows Explorer at:

Or in VS Code:

Quick Start

New Project

Existing Project

If you have an existing Laravel project, copy it to ~/projects/ and configure it:

Required .env changes for existing projects:

Quick setup script for existing projects:

Checklist for existing projects:

• [ ] Project copied to ~/projects/<name>/
• [ ] Database created (docker-local db:create <name>)
• [ ] .env updated with Docker service names (mysql, redis, mailpit)
• [ ] Unique CACHE_PREFIX set (e.g., myproject_)
• [ ] Unique REDIS_*_DB numbers assigned (if running multiple projects)
• [ ] Dependencies installed (composer install)
• [ ] Migrations run (php artisan migrate)
• [ ] Host added to /etc/hosts or dnsmasq configured

CLI Commands

Setup & Diagnostics

Fix command options:

The fix command automatically detects and resolves issues like:

• Docker daemon not running
• Stopped containers
• Missing systemd-resolved configuration for *.test DNS
• Missing dnsmasq configuration
• /etc/hosts not configured

Environment Management

Project Commands

make:laravel creates everything automatically:

• Laravel project via Composer
• Database (MySQL or PostgreSQL) + testing database
• MinIO bucket for file storage
• Unique Redis DB numbers for cache/session/queue
• Unique cache prefix and Reverb credentials
• Configured .env with all Docker service connections

Development Commands

Artisan Shortcuts

Database Commands

Queue Commands

Xdebug Commands

Startup Commands

Configure docker-local to start automatically when your computer boots:

Platform-specific behavior:

Environment Verification

Configuration

Configuration is stored in ~/.config/docker-local/config.json:

Directory Structure

docker-local operates across three locations:

Package Structure (Source Code)

User Configuration (~/.config/docker-local/)

Created by docker-local init, persists across updates:

Projects Directory (~/projects/)

Each Laravel project is automatically accessible via HTTPS:

Understanding Environment Files

docker-local uses two separate .env files for different purposes:

.env.example (Docker/Infrastructure)

Controls how Docker containers are built and connected:

This file is copied to ~/.config/docker-local/.env and read by docker-compose.yml via ${VARIABLE} syntax.

laravel.env.example (Application)

Controls how Laravel connects to services from inside the container:

This file is copied to each project's .env (~/projects/my-app/.env) and read by Laravel via env() and config().

Why Both Files Exist

Key insight: The same service has different addresses depending on where you're accessing it from:

The Docker .env configures what ports are exposed to your machine, while the Laravel .env configures how to reach services via Docker's internal network.

Related Files

The stubs/ versions contain placeholders like {{PROJECT_NAME}} for automated project creation via docker-local make:laravel.

Services

URLs

Ports

Default Credentials

All Included Services

All services are now enabled by default. Simply run:

RTMP Server (Live Streaming)

The RTMP server provides live streaming with HLS delivery:

RTMP Configuration:

Customizing RTMP:

To add project-specific webhooks (e.g., on_publish callbacks), create a custom config:

Node.js Container

A dedicated Node.js 20 container for long-running build processes:

PostgreSQL with pgvector

PostgreSQL 17 now includes the pgvector extension for AI embeddings:

AI/Whisper Transcription

Two options for speech-to-text transcription:

Option 1: Whisper API Container (Recommended)

A dedicated Whisper ASR webservice with OpenAI-compatible HTTP API (using faster-whisper-server):

Laravel Configuration (.env):

Example API Call:

Web UI: https://whisper.localhost

Option 2: PHP-AI Container (CLI)

For direct CLI access to Whisper:

Whisper Models:

Configure the model in .env:

tusd — Resumable uploads (TUS protocol)

tusd is the reference TUS server (Go) for resumable uploads. It accepts chunked HTTP uploads from browsers (Uppy.js, TusUpload, etc.) and streams them directly to MinIO/S3 — no PHP worker in the hot path, safe for GB-scale files on flaky connections.

Endpoints:

Configuration (.env):

tusd reads S3 credentials from MINIO_ROOT_USER / MINIO_ROOT_PASSWORD and writes directly to the MinIO container at http://minio:9000. On upload completion, the file lives under s3://$TUSD_S3_BUCKET/<upload-id> and <upload-id>.info.

Example upload (Uppy.js on the client, nothing server-side):

For authorized uploads in production, configure tusd hooks (-hooks-http) to call a Laravel endpoint that validates the user and allowed bucket prefix before accepting a new upload.

Laravel Workers (Horizon, Reverb, Scheduler)

For Laravel-specific services, use the override stub as a template:

Available templates:

• Horizon - Queue worker with Laravel Horizon
• Reverb - WebSocket server for real-time features
• Scheduler - Cron-like task scheduler
• Elasticsearch/Meilisearch - Full-text search
• Soketi - Open-source Pusher alternative

Multi-Project Support

docker-local supports multiple Laravel projects sharing the same Docker services. Each project gets complete automatic isolation to prevent data leakage between projects.

What Gets Created Automatically

When you create a project with docker-local make:laravel myapp, everything is set up automatically:

Automatic Isolation Details

Redis Database Allocation

Redis has 16 databases (0-15). Each project uses 3 databases:

This allows up to 5 fully isolated projects. Beyond that, DB numbers wrap around (with a warning).

PostgreSQL vs MySQL

Both database engines are available. Use the --postgres flag:

PostgreSQL projects automatically get these extensions:

• uuid-ossp - UUID generation
• pgcrypto - Cryptographic functions
• vector - pgvector for AI embeddings

Conflict Detection

Example conflict output:

Running Multiple Projects Simultaneously

All projects can run at the same time without conflicts:

Each project has its own:

• Database (no shared tables)
• Cache (no key collisions)
• Sessions (users stay logged in to their project)
• Queues (jobs don't mix between projects)
• File storage (separate MinIO buckets)

Migrating from Project-Specific Docker

If your project has its own Docker configuration, you can migrate to docker-local for a shared, centralized environment.

What docker-local Provides

What Stays Project-Specific

These should remain in your project's docker-compose.override.yml:

Migration Steps

1. Copy your project's custom services to an override file:

2. Add Laravel-specific services:

3. Update your .env for docker-local:

4. For RTMP/streaming features:

5. Remove old Docker files from your project:

6. Start using docker-local:

Example: pcast Migration

For a complex streaming application like pcast:

Before (project-specific):

After (docker-local):

Start docker-local (all features included):

Benefits:

• Shared services across all projects
• Centralized updates and maintenance
• Consistent development environment
• Smaller project footprint

IDE Integration

VS Code

1. Install PHP Debug extension

2. Create .vscode/launch.json:

3. Start debugging: F5

PhpStorm

1. Settings → PHP → Debug → Port: 9003
2. Settings → PHP → Servers:
   • Name: docker
   • Host: localhost, Port: 443
   • Path mappings: /var/www/project → ~/projects/project
3. Click "Start Listening for PHP Debug Connections"

Troubleshooting

General Diagnostics

The fix command is the recommended first step when troubleshooting - it automatically diagnoses issues and attempts to fix them where possible.

Common Issues

"Docker daemon is not running"

"Port already in use"

"Permission denied" errors

"*.test domains not resolving"

If dnsmasq is working but system DNS isn't:

SSL Certificate Issues

Cleaning Up

Using Local PHP

If you prefer using your local PHP installation with Docker services:

The setup:hosts command adds to /etc/hosts:

Shell Completion

Bash

Zsh

Updating

Extending

Adding Custom Services

Create ~/.config/docker-local/docker-compose.override.yml:

Then restart:

Custom PHP Configuration

Create ~/.config/docker-local/php/custom.ini:

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

License

MIT License. See LICENSE for details.

Made with :heart: for Laravel developers.