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:
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.
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)yamlmeilisearch: 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_network2Configure Laravel Scout, Postgres, and Redis Hostnames in .env
.envSet SCOUT_QUEUE=true so model updates dispatch asynchronously via Redis to your queue worker container instead of slowing down HTTP requests.
.envdotenvDB_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_key3Sync Scout Index Settings and Import Initial Models
terminalAfter docker compose up -d confirms all healthchecks pass, run Laravel migrations, sync filterable/sortable Scout attributes, and import existing records.
terminalbashdocker 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"4Verify Queue Worker Indexing Throughput in Container Logs
terminalTail the worker logs while creating or updating a searchable model to confirm queued MakeSearchable jobs execute cleanly against http://meilisearch:7700.
terminalbashdocker 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.
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.
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.
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.
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:
Validate Laravel 11/12 .env files locally in your browser. Fix InvalidFileException, unquoted # in DB_PASSWORD, invalid base64 APP_KEY, and config:cache traps.
Configure Nginx reverse proxy for Laravel Octane (FrankenPHP/Swoole) on port 8000 and Laravel Reverb WebSockets on port 8080 with SSL and 3600s timeouts.
Fix Laravel Sanctum SPA cookie CORS errors. Validate supports_credentials, SANCTUM_STATEFUL_DOMAINS, X-XSRF-TOKEN preflight headers, and SameSite rules.
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.
Related Docker Compose Stack Guides
Browse all 10 Compose stacks →Docker Compose Laravel + MySQL 8 + Redis Queue Stack & Healthcheck Guide
Generate a production Docker Compose file for Laravel 11/12 with MySQL 8, Redis 7, and queue:work using mysqladmin and redis-cli service_healthy probes.
Docker Compose Laravel Octane + PostgreSQL 16 + Reverb WebSockets Guide
Generate a Docker Compose stack for Laravel Octane, PostgreSQL 16, Redis 7, and Laravel Reverb WebSockets with pg_isready healthchecks and firewall safety.
Docker Compose FastAPI + PostgreSQL 16 + Celery Worker Healthcheck Guide
Build a production Docker Compose stack for Python FastAPI, PostgreSQL 16, Redis 7, and Celery workers with pg_isready healthchecks and Alembic migrations.
Docker Compose Node.js + BullMQ Worker + Redis 7 + PostgreSQL 16 Guide
Generate a Docker Compose config for Node.js APIs, BullMQ background workers, Redis 7, and PostgreSQL 16 with native healthchecks and noeviction Redis safety.