docker-local-env

Check and manage .env configuration for docker-local projects - conflict detection, unique IDs, isolation settings

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 7, 2026

When & Why to Use This Skill

The Docker-Local Environment skill is a specialized utility designed to manage, audit, and optimize .env configurations for local Docker development. It streamlines the setup process by automatically detecting resource conflicts—such as overlapping database names or Redis IDs—and generating unique isolation settings to ensure multiple projects can run concurrently without data corruption or service interference.

Use Cases

  • Conflict Detection: Identify overlapping database names, Redis DB numbers, and cache prefixes across multiple local projects to prevent data collisions.
  • Automated Configuration: Generate new .env files with unique isolation IDs, including specific Redis database allocations and unique S3/MinIO bucket names.
  • Environment Verification: Audit existing .env files to ensure service hostnames are correctly configured for container-to-container communication (e.g., using 'mysql' instead of 'localhost').
  • Project Isolation: Set up distinct WebSocket (Reverb) credentials and unique cache prefixes for every project to maintain a clean development environment.
namedocker-local-env
descriptionCheck and manage .env configuration for docker-local projects - conflict detection, unique IDs, isolation settings

Docker-Local Environment Skill

Overview

This skill manages .env configuration for docker-local projects:

  • Verify .env settings
  • Detect conflicts between projects
  • Generate unique isolation IDs
  • Update existing configurations

MANDATORY: Prerequisite Check

Before ANY docker-local command, verify installation:

which docker-local > /dev/null 2>&1

If docker-local is NOT found:

  1. Stop and ask the user if they want to install it
  2. If yes, install via: composer global require mwguerra/docker-local
  3. Add to PATH: export PATH="$HOME/.composer/vendor/bin:$PATH"
  4. Initialize: docker-local init
  5. Verify: which docker-local && docker-local --version

Understanding Environment Files

Docker-local uses two separate .env files:

File Purpose Location
Docker .env Container configuration ~/.config/docker-local/.env
Laravel .env Application settings ~/projects/<project>/.env

Docker .env (Infrastructure)

Controls how containers are built:

PROJECTS_PATH=~/projects
MYSQL_PORT=3306
MYSQL_ROOT_PASSWORD=secret
XDEBUG_ENABLED=true

Laravel .env (Application)

Controls how Laravel connects to services:

DB_HOST=mysql                 # Docker service name
DB_PORT=3306
REDIS_HOST=redis
MAIL_HOST=mailpit

Key insight: Services have different addresses:

  • From host: localhost:3306
  • From container: mysql:3306

Environment Commands

Check Current Project

# Verify .env configuration
docker-local env:check

# Checks:
# - Service hostnames (mysql vs localhost)
# - Required variables present
# - Redis DB numbers
# - Cache prefix

Audit All Projects

# Check ALL projects for conflicts
docker-local env:check --all

# Detects:
# - Duplicate database names
# - Overlapping Redis DBs
# - Duplicate cache prefixes
# - Shared MinIO buckets

Generate New .env

# Create new .env with unique IDs
docker-local make:env

# Generates:
# - Unique CACHE_PREFIX
# - Available REDIS_*_DB numbers
# - Unique REVERB credentials
# - Correct service hostnames

Update Existing .env

# Update .env with current settings
docker-local update:env

# Preserves:
# - Custom settings
# - API keys
# - User modifications

Isolation Settings

Database Isolation

Each project gets its own database:

DB_DATABASE=myapp           # Main database
# Also created: myapp_testing

Redis Isolation

Each project uses 3 Redis databases:

REDIS_CACHE_DB=0
REDIS_SESSION_DB=1
REDIS_QUEUE_DB=2

Allocation pattern:

Project # Cache Session Queue
1 0 1 2
2 3 4 5
3 6 7 8
4 9 10 11
5 12 13 14

Cache Prefix Isolation

CACHE_PREFIX=myapp_

Prevents cache key collisions between projects.

MinIO Bucket Isolation

AWS_BUCKET=myapp

Each project gets its own S3 bucket.

Reverb/WebSocket Isolation

REVERB_APP_ID=123456
REVERB_APP_KEY=random-key
REVERB_APP_SECRET=random-secret

Each project gets unique WebSocket credentials.

Conflict Detection

Example Conflict Report

┌─ Environment Check: ~/projects/shop ─────────────────────────────┐

✓ Database Configuration
  DB_HOST: mysql (correct)
  DB_DATABASE: shop

✓ Redis Configuration
  CACHE_DB: 6
  SESSION_DB: 7
  QUEUE_DB: 8

⚠ CACHE_PREFIX Conflict
  Current: laravel_cache_
  Conflicts with: blog, api

  Fix: Change to 'shop_' in .env:
       CACHE_PREFIX=shop_

✓ MinIO Configuration
  Bucket: shop

└──────────────────────────────────────────────────────────────────┘

Common Conflicts

Cache Prefix Conflict

⚠ CACHE_PREFIX conflict with 'other-project'
    Both use: laravel_cache_

Why: Cache data shared/corrupted between projects
Fix: CACHE_PREFIX=unique_project_name_

Redis DB Overlap

⚠ REDIS_CACHE_DB conflict
    Both projects use DB 0

Why: Cache data mixed between projects
Fix: Use next available set (3, 4, 5)

Database Name Collision

⚠ DB_DATABASE conflict
    Both projects use: laravel

Why: Data will be shared/overwritten
Fix: Use unique database name per project

Required .env Variables

Core Settings

APP_NAME=MyApp
APP_KEY=base64:...
APP_ENV=local
APP_DEBUG=true
APP_URL=https://myapp.test

Database (MySQL)

DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=myapp
DB_USERNAME=laravel
DB_PASSWORD=secret

Database (PostgreSQL)

DB_CONNECTION=pgsql
DB_HOST=postgres
DB_PORT=5432
DB_DATABASE=myapp
DB_USERNAME=laravel
DB_PASSWORD=secret

Redis

REDIS_HOST=redis
REDIS_PASSWORD=null
REDIS_PORT=6379
REDIS_CACHE_DB=0
REDIS_SESSION_DB=1
REDIS_QUEUE_DB=2

Cache

CACHE_DRIVER=redis
CACHE_PREFIX=myapp_

Mail

MAIL_MAILER=smtp
MAIL_HOST=mailpit
MAIL_PORT=1025

S3/MinIO

FILESYSTEM_DISK=s3
AWS_ENDPOINT=http://minio:9000
AWS_ACCESS_KEY_ID=minio
AWS_SECRET_ACCESS_KEY=minio123
AWS_BUCKET=myapp
AWS_USE_PATH_STYLE_ENDPOINT=true

Fixing Common Issues

Wrong Database Host

# Wrong (from host perspective)
DB_HOST=localhost

# Correct (from container)
DB_HOST=mysql

Missing Unique IDs

# Generate everything
docker-local make:env

# Or manually:
CACHE_PREFIX=myapp_
REDIS_CACHE_DB=3
REDIS_SESSION_DB=4
REDIS_QUEUE_DB=5

Reset to Defaults

# Backup current .env
cp .env .env.backup

# Generate fresh .env
docker-local make:env

# Restore custom settings
# Manually copy API keys, etc. from backup

$ARGUMENTS