Docker Health Monitoring

Runtime optimizations and health monitoring for production/staging deployments using Docker ENTRYPOINT pattern and Spatie Health package.

Overview

Docker ENTRYPOINT pattern provides:

• Runtime Laravel optimization at container startup
• Health monitoring via Spatie Health package
• Portable Docker images across environments
• Consistent initialization across container restarts

Docker ENTRYPOINT Pattern

What It Does

Executes Laravel optimization commands at container startup (runtime) instead of Docker build time:

• php artisan filament:optimize - Optimizes FilamentPHP assets
• php artisan optimize - Caches Laravel routes, views, config

Benefits

• Config cache uses actual runtime environment variables
• Portable Docker images work across dev/staging/production
• OptimizedAppCheck passes with proper caching state
• Consistent initialization across container restarts

Implementation

Shared entrypoint script: backend/docker/common/docker-entrypoint.sh

Used by:

• php-fpm container
• queue-worker container
• scheduler container

Health Monitoring

Configured Checks

Check	Purpose	Configuration
DatabaseCheck	Verify database connectivity	Default
CacheCheck	Verify cache connectivity	Default
UsedDiskSpaceCheck	Monitor disk usage	Warn: 70%, Fail: 90%
OptimizedAppCheck	Verify Laravel optimization (prod/staging)	Checks config/route cache
DebugModeCheck	Ensure debug mode off (prod/staging)	Fails if APP_DEBUG=true
EnvironmentCheck	Verify correct environment (prod/staging)	Checks APP_ENV value

External Monitoring

Queue and scheduler health are monitored externally via:

• AWS CloudWatch for queue metrics
• Container orchestration health checks
• Application performance monitoring (APM) tools

Production Containers

Container Names

php-fpm:      # Web application
queue-worker: # Processes background jobs
scheduler:    # Runs scheduled tasks (schedule:work)

Scheduler Container

Dedicated container running Laravel scheduler in production/staging:

php artisan schedule:work

Purpose: Executes scheduled commands:

• telescope:prune - Daily cleanup (keeps 14 days, preserves exceptions)
• model:prune - Daily health history cleanup (5 days retention)

Deployment: Configured in infrastructure templates:

• infra-volare/.../staging-1/.../api-staging-1.user-data.tmpl
• infra-volare/.../production-1/.../api-production-1.user-data.tmpl

Health Endpoints

JSON Health Endpoint

GET /health

Returns JSON with all check results:

{
  "finishedAt": "2025-11-14 17:30:00",
  "checkResults": [
    {
      "name": "Database",
      "status": "ok"
    },
    {
      "name": "Queue",
      "status": "ok",
      "notificationMessage": "All queues running"
    }
  ]
}

Response Codes:

• 200 - All checks passed
• 503 - One or more checks failed

Health Dashboard

GET /health-dashboard

Authenticated UI showing cached health check results (requires login).

Manual Health Check

php artisan health:check

Configuration

Environment Variables

HEALTH_NOTIFICATION_EMAIL=ops@example.com
HEALTH_DB_CONNECTION=pgsql

Config File

File: config/health.php

• Result storage: Database (5-day history)
• Notifications: Email (throttled to 1/hour)

Load Balancer Integration

Configure external monitoring (e.g., AWS ALB, DataDog) to poll /health endpoint:

Health Check Settings:

• Path: /health
• Interval: 30 seconds
• Timeout: 5 seconds
• Healthy threshold: 2
• Unhealthy threshold: 2

Troubleshooting

OptimizedAppCheck Failing

1. Ensure ENTRYPOINT executes before service starts
2. Check container logs for optimization errors
3. Verify runtime environment variables set correctly

# Check if optimization ran
docker logs php-fpm | grep "artisan optimize"

Disk Space Warning

1. Check disk usage:

df -h

2. Clean old logs:

php artisan telescope:prune

3. Prune health history: Daily scheduled task handles this

Database Connection Issues

1. Check database connectivity:

php artisan tinker
>>> DB::connection()->getPdo();

2. Verify environment variables:

php artisan config:show database

Cache Connection Issues

1. Check Redis connectivity:

php artisan tinker
>>> Cache::get('test');

2. Verify Redis configuration:

php artisan config:show cache

Spatie Health Package

Adding Custom Checks

app/Providers/HealthServiceProvider.php

use Spatie\Health\Facades\Health;
use Spatie\Health\Checks\Checks\DatabaseCheck;

Health::checks([
    DatabaseCheck::new(),
    CacheCheck::new(),
    UsedDiskSpaceCheck::new()
        ->warnWhenUsedSpaceIsAbovePercentage(70)
        ->failWhenUsedSpaceIsAbovePercentage(90),
    // Add custom checks here
]);

Custom Check Example

use Spatie\Health\Checks\Check;
use Spatie\Health\Checks\Result;

class QueueSizeCheck extends Check
{
    public function run(): Result
    {
        $queueSize = Queue::size('default');

        if ($queueSize > 1000) {
            return Result::make()
                ->failed("Queue size is {$queueSize}");
        }

        if ($queueSize > 500) {
            return Result::make()
                ->warning("Queue size is {$queueSize}");
        }

        return Result::make()
            ->ok("Queue size is {$queueSize}");
    }
}

Related Documentation

• Queue System - Queue infrastructure
• Health Monitoring - Application health checks