Foxws
Pods

Health Checks

Health checks

Pods doesn't ship a health check package. Pick what fits how you run it.

Container health checks

Laravel already serves /up (see health: in bootstrap/app.php). It boots the app and returns 200, or 500 when booting fails. For Docker, Podman or Kubernetes that's usually enough.

Docker / Podman Compose:

services:
    app:
        healthcheck:
            test: ['CMD', 'curl', '-fsS', 'http://localhost:8000/up']
            interval: 30s
            timeout: 5s
            retries: 3
            start_period: 20s

Containerfile / Dockerfile:

HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
  CMD curl -fsS http://localhost:8000/up || exit 1

Use the port Octane listens on. If the image has no curl, use wget -qO- http://localhost:8000/up instead.

Queue and scheduler containers don't serve HTTP, so leave them without an HTTP health check (HealthCmd=none in a Quadlet) and let the restart policy bring them back when the process exits.

To check the database or Redis on /up, listen for the DiagnosingHealth event and throw when a dependency is down:

use Illuminate\Foundation\Events\DiagnosingHealth;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Event;

Event::listen(DiagnosingHealth::class, function (): void {
    DB::connection()->getPdo();
});

spatie/laravel-health

Use spatie/laravel-health when you want stored results, notifications on failures, a JSON results page or Oh Dear integration.

Install

composer require spatie/laravel-health
php artisan vendor:publish --tag="health-config"
php artisan vendor:publish --tag="health-migrations"
php artisan migrate

Register the checks

Create src/Foundation/Providers/HealthServiceProvider.php and add it to bootstrap/providers.php:

<?php

declare(strict_types=1);

namespace Foundation\Providers;

use Domain\Users\Models\User;
use Illuminate\Support\Facades\Gate;
use Illuminate\Support\ServiceProvider;
use Spatie\Health\Checks\Checks\CacheCheck;
use Spatie\Health\Checks\Checks\DatabaseCheck;
use Spatie\Health\Checks\Checks\DebugModeCheck;
use Spatie\Health\Checks\Checks\EnvironmentCheck;
use Spatie\Health\Checks\Checks\OptimizedAppCheck;
use Spatie\Health\Checks\Checks\UsedDiskSpaceCheck;
use Spatie\Health\Facades\Health;

class HealthServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        $this->configureChecks();
        $this->configureGates();
    }

    protected function configureChecks(): void
    {
        Health::checks([
            DatabaseCheck::new(),
            CacheCheck::new(),
            UsedDiskSpaceCheck::new()
                ->warnWhenUsedSpaceIsAbovePercentage(70)
                ->failWhenUsedSpaceIsAbovePercentage(90),
            DebugModeCheck::new(),
            EnvironmentCheck::new(),
            OptimizedAppCheck::new()
                ->if(app()->isProduction()),
        ]);
    }

    protected function configureGates(): void
    {
        Gate::define('viewHealth', fn (User $user): bool => $user->isSuperAdmin());
    }
}

Schedule and prune

In routes/console.php:

use Illuminate\Database\Console\PruneCommand;
use Spatie\Health\Commands\RunHealthChecksCommand;
use Spatie\Health\Models\HealthCheckResultHistoryItem;

Schedule::command(RunHealthChecksCommand::class)
    ->everyFiveMinutes();

Schedule::command(PruneCommand::class, [
    '--model' => [
        HealthCheckResultHistoryItem::class,
    ]])
    ->withoutOverlapping(10)
    ->dailyAt('01:00');

Results page

In routes/web.php:

use Spatie\Health\Http\Controllers\HealthCheckJsonResultsController;

Route::get('/health', HealthCheckJsonResultsController::class)
    ->middleware(['auth', 'can:viewHealth', 'cache.bypass'])
    ->name('health');

Add a link for super-admins in resources/js/components/Ui/UserMenu.vue, next to the Application item:

import { health } from '@/routes'

{
  label: 'Health',
  icon: 'i-lucide-heart-pulse',
  to: health.url(),
  target: '_blank',
  external: true,
},

To let an external monitor read the results without logging in, set HEALTH_SECRET_TOKEN in .env and send it in the X-Secret-Token header.

Test

tests/Feature/Health/HealthCheckTest.php:

<?php

declare(strict_types=1);

use Domain\Users\Models\User;

it('shows the health check results to a super-admin', function () {
    $user = User::factory()->create();
    $user->assignRole('super-admin');

    $this->artisan('health:check')->assertSuccessful();

    $this->actingAs($user)
        ->getJson(route('health'))
        ->assertSuccessful()
        ->assertJsonStructure(['finishedAt', 'checkResults']);
});

it('hides the health check results from regular users', function () {
    $this->actingAs(User::factory()->create())
        ->getJson(route('health'))
        ->assertForbidden();
});