Docker Compose Builder · Laravel / Postgres + Meilisearch

Docker Compose Laravel + PostgreSQL 16 + Meilisearch + Redis Stack Guide

Generate a Compose Specification docker-compose.yml and matching .env.example for Laravel / Postgres + Meilisearch with native binary healthchecks, service_healthy boot ordering, and firewall-safe port bindings.

Written & verified by Chathura Prabashana · Updated November 2026

1. Adjust stack settings or load a test scenario2. Inspect live diagnostics3. Copy generated config
Quick-Test Scenarios:

1. Runtime & Data Services

2. Healthchecks, Workers & Security

# docker-compose.yml — Modern Compose Specification (no obsolete 'version:' attribute)
# Generated by OpsCheck DevTools (Laravel PHP)
name: laravel_scout_stack

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "127.0.0.1:8000:8000"
    environment:
      DB_HOST: postgres
      DB_PORT: "5432"
      REDIS_HOST: redis
      REDIS_PORT: "6379"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - app_network

  worker:
    build:
      context: .
      dockerfile: Dockerfile
    command: php artisan queue:work --sleep=3 --tries=3 --max-time=3600
    restart: unless-stopped
    env_file:
      - .env
    environment:
      DB_HOST: postgres
      DB_PORT: "5432"
      REDIS_HOST: redis
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - app_network

  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${DB_DATABASE:-app_db}
      POSTGRES_USER: ${DB_USERNAME:-app}
      POSTGRES_PASSWORD: ${DB_PASSWORD:-change_me_strong}
    # Kept strictly internal on app_network (prevents Docker iptables UFW bypass)
    expose:
      - "5432"
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER:-app} -d $${POSTGRES_DB:-app}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s
    networks:
      - app_network

  redis:
    image: redis:7-alpine
    command: redis-server --appendonly yes
    restart: unless-stopped
    expose:
      - "6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
    networks:
      - app_network

networks:
  app_network:
    driver: bridge

volumes:
  db_data:
  redis_data:
Service Boot Orderbridge: app_network
postgres(healthy)+redis(healthy)appworker

Healthcheck & Security Diagnostics

Compose Spec v2+
  • passStartup Race Condition Prevented (condition: service_healthy)

    app and worker will wait until postgres and redis pass their native healthchecks before starting.

  • infoInternal Bridge DNS Hostnames (Never Use localhost Inside Containers)

    Connect over the shared app_network using Docker service names: DB_HOST=postgres (port 5432), REDIS_HOST=redis (port 6379). Inside the "app" container, 127.0.0.1/localhost points only to "app" itself and always refuses DB/broker connections.

  • passFirewall-Safe Port Exposure Enabled (127.0.0.1 / Internal expose:)

    Database and broker ports stay strictly isolated on app_network via expose:, and app ports bind to 127.0.0.1 so Docker never bypasses host UFW/nftables rules.

  • passNative Probe Binaries Used (pg_isready & redis-cli ping)

    Generated healthchecks invoke built-in service binaries rather than curl or wget, avoiding false "unhealthy" states in minimal Alpine and slim official images.

  • passPersistent Named Volumes Declared (db_data, redis_data)

    Top-level named volumes preserve database tables and broker queues across container rebuilds and "docker compose down" (data is only removed if you pass -v).

Runs locally in your browser. Compose YAML and environment templates are generated client-side.

Typical Container Boot & Connection Error (Laravel / Postgres + Meilisearch)

When depends_on lacks condition: service_healthy or internal service hostnames are misconfigured in .env, container logs typically surface this error during startup:

docker compose logs (Startup Failure)

Meilisearch\Exceptions\CommunicationException: Failed to connect to localhost port 7700 after 0 ms: Couldn't connect to server

Container Boot Ordering, Bridge DNS & Persistence for Laravel / Postgres + Meilisearch

Adding instant, typo-tolerant full-text search to a Laravel + PostgreSQL 16 + Redis 7 application using Laravel Scout and Meilisearch inside Docker Compose delivers Algolia-grade search latency with zero external SaaS fees. Because indexing Eloquent models asynchronously runs through Laravel queues, coordinating four services, app, worker, postgres, redis, and meilisearch, requires clean bridge DNS and healthcheck gating.

A common failure when integrating Meilisearch into Compose is leaving MEILISEARCH_HOST=http://127.0.0.1:7700 in .env: both the Laravel web container and the queue worker container then try to reach port 7700 inside themselves and fail with CommunicationException. Setting MEILISEARCH_HOST=http://meilisearch:7700 resolves cleanly over app_network.

Equally important is protecting Meilisearch's master key and persistent LMDB index volume. In production mode (MEILI_ENV=production), Meilisearch refuses to start unless MEILI_MASTER_KEY is at least 16 bytes long, and omitting a named meilisearch_data volume mounted at /meili_data forces a full Scout re-index on every container rebuild.

By combining pg_isready for PostgreSQL 16, redis-cli ping for Redis 7, and a curl/wget health check on Meilisearch's /health endpoint with condition: service_healthy, your Laravel app and Scout indexing worker boot cleanly in deterministic order with zero failed queued index jobs.

Finally, keep PostgreSQL (5432), Redis (6379), and Meilisearch (7700) strictly internal via expose: on app_network so search queries flow through authenticated Laravel endpoints; or only publish a read-only search API key if frontend clients query Meilisearch through a hardened Nginx reverse proxy.

To keep Laravel Scout search indexes consistently synchronized with PostgreSQL 16 in production, monitor failed Redis queue jobs (php artisan queue:failed) and test Meilisearch container restarts against your named meilisearch_data volume before launch. Keeping PostgreSQL, Redis, and Meilisearch strictly isolated on app_network while serving search through authenticated Laravel routes delivers fast typo-tolerant search with strong defense in depth.

Step-by-Step Laravel / Postgres + Meilisearch Docker Compose Setup Guide

Follow each step below to pair the generated Compose file with accurate container DNS variables, safe database migrations, and zero-downtime restarts.

  1. 1Add the Meilisearch Service With Persistent Index Volume

    docker-compose.yml (meilisearch service snippet)

    Append the getmeili/meilisearch container alongside the generated app, worker, postgres, and redis services, mounting meilisearch_data:/meili_data so search indexes survive rebuilds.

    docker-compose.yml (meilisearch service snippet)yaml
      meilisearch:
        image: getmeili/meilisearch:v1.11
        restart: unless-stopped
        environment:
          MEILI_ENV: production
          MEILI_MASTER_KEY: ${MEILISEARCH_KEY:-replace_with_32_char_secret_key}
          MEILI_NO_ANALYTICS: "true"
        expose:
          - "7700"
        volumes:
          - meilisearch_data:/meili_data
        healthcheck:
          test: ["CMD", "wget", "--no-verbose", "--spider", "http://127.0.0.1:7700/health"]
          interval: 10s
          timeout: 5s
          retries: 5
        networks:
          - app_network
  2. 2Configure Laravel Scout, Postgres, and Redis Hostnames in .env

    .env

    Set SCOUT_QUEUE=true so model updates dispatch asynchronously via Redis to your queue worker container instead of slowing down HTTP requests.

    .envdotenv
    DB_CONNECTION=pgsql
    DB_HOST=postgres
    DB_PORT=5432
    DB_DATABASE=app_db
    DB_USERNAME=app
    DB_PASSWORD=change_me_strong
    
    QUEUE_CONNECTION=redis
    REDIS_HOST=redis
    
    SCOUT_DRIVER=meilisearch
    SCOUT_QUEUE=true
    MEILISEARCH_HOST=http://meilisearch:7700
    MEILISEARCH_KEY=replace_with_32_char_secret_key
  3. 3Sync Scout Index Settings and Import Initial Models

    terminal

    After docker compose up -d confirms all healthchecks pass, run Laravel migrations, sync filterable/sortable Scout attributes, and import existing records.

    terminalbash
    docker compose up -d --build
    docker compose exec app php artisan migrate --force
    docker compose exec app php artisan scout:sync-index-settings
    docker compose exec app php artisan scout:import "App\\Models\\Product"
  4. 4Verify Queue Worker Indexing Throughput in Container Logs

    terminal

    Tail the worker logs while creating or updating a searchable model to confirm queued MakeSearchable jobs execute cleanly against http://meilisearch:7700.

    terminalbash
    docker compose logs -f worker

Common Laravel / Postgres + Meilisearch Docker Compose Pitfalls

Avoid these three container orchestration mistakes before deploying your Compose stack onto staging or production servers.

Pitfall 1

Leaving MEILI_MASTER_KEY Empty or Shorter Than 16 Bytes in Production

When MEILI_ENV=production is set, Meilisearch exits immediately on startup if MEILI_MASTER_KEY is missing or under 16 bytes. Generate a 32-byte key via openssl rand -hex 32 and store it in .env.

Pitfall 2

Upgrading Meilisearch Minor Versions Without Exporting a Dump First

Meilisearch LMDB database files are not always binary-compatible across major/minor releases (e.g., v1.9 -> v1.11). Pin an exact image tag like getmeili/meilisearch:v1.11 instead of :latest and use Scout re-imports or Meilisearch dumps when upgrading.

Pitfall 3

Synchronous Scout Indexing Blocking Laravel HTTP Responses

Leaving SCOUT_QUEUE=false causes every Eloquent save() to block waiting on Meilisearch HTTP indexing. Setting SCOUT_QUEUE=true offloads indexing to your dedicated worker container over Redis.

Related Tools

Pair Your Docker Compose Stack With .env Linting, Nginx TLS & CORS Checks

Validate your .env file for unescaped $$ interpolation or leaked secrets, configure Nginx DNS resolution, and verify cross-origin headers:

Frequently Asked Questions

Why does Laravel Scout say "Failed to connect to localhost port 7700"?
Inside the Laravel container, localhost points to the PHP container rather than Meilisearch. Change MEILISEARCH_HOST to http://meilisearch:7700 so Docker resolves the Meilisearch container over app_network.
Should I publish Meilisearch port 7700 directly to the internet for instant frontend search?
Avoid exposing port 7700 directly via Docker ports. If your frontend queries Meilisearch directly, reverse-proxy only search endpoints through Nginx TLS with a scoped read-only search key; never your master key.
How much RAM should I allocate to Meilisearch in Docker Compose?
Meilisearch uses memory-mapped LMDB files and performs best when its index fits comfortably in RAM. You can optionally set deploy.resources.limits.memory or MEILI_MAX_INDEXING_MEMORY on modest VPS instances.
Will docker compose down erase my Meilisearch search indexes?
No, as long as meilisearch_data:/meili_data is declared under top-level volumes: and you do not pass the -v flag to docker compose down.
Browse all 10 Compose stacks →