docker-laravel-base/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Docker base image for Laravel applications using FrankenPHP, designed to be lightweight and production-ready. The repository contains minimal configuration files to create a containerized Laravel runtime environment.

Architecture

• Base Image: Uses dunglas/frankenphp as the foundation
• Server: FrankenPHP with Laravel Octane integration
• Database: Configured for SQLite by default (with support for PostgreSQL and MySQL extensions)
• Application: Expects Laravel application code to be mounted at /app

Key Files

• Dockerfile: Main container configuration with PHP extensions and entrypoint setup
• entrypoint.sh: Container startup script that handles Laravel initialization
• .env.docker: Production environment configuration for containerized Laravel apps
• .github/workflows/build.yml: CI/CD pipeline for building and pushing to Docker registry

Docker Commands

Building the Image

docker build -t laravel-base .

Running a Container

# Assumes Laravel application code is mounted to /app
docker run -p 8000:8000 -v /path/to/laravel/app:/app laravel-base

Container Behavior

The entrypoint script (entrypoint.sh) automatically:

1. Runs database migrations (php artisan migrate --force)
2. Creates storage symlink (php artisan storage:link)
3. Generates APP_KEY if not set in environment
4. Clears and caches configuration and views
5. Executes custom hook script if /app/hook.sh exists
6. Starts supervisor services (queue worker and/or scheduler) if enabled via environment variables
7. Starts FrankenPHP server on port 8000 with admin port 2019

Hook System

Applications extending this base image can provide a hook.sh script at /app/hook.sh to run custom initialization commands. The hook script is executed after Laravel setup but before the server starts.

Example Usage in Extending Dockerfile

FROM gitgud.foo/thegrind/laravel-base:latest
COPY ./hook.sh /app/hook.sh
# Your application code and additional setup

Example hook.sh

#!/bin/sh
# Custom application initialization
php /app/artisan db:seed --force
php /app/artisan queue:restart

Queue Workers and Scheduler

The base image includes supervisor configuration for Laravel queue workers and scheduler. These can be optionally enabled by extending images using environment variables:

• ENABLE_QUEUE_WORKER=true - Starts Laravel queue worker process
• ENABLE_SCHEDULER=true - Starts Laravel scheduler process

Supervisor Configuration Files

• supervisord.conf - Main supervisor configuration
• laravel-queue.conf - Queue worker process configuration
• laravel-scheduler.conf - Scheduler process configuration

Usage Example

FROM gitgud.foo/thegrind/laravel-base:latest
ENV ENABLE_QUEUE_WORKER=true
ENV ENABLE_SCHEDULER=true
# Your application setup...

Environment Configuration

The .env.docker file is copied into the container and includes:

• SQLite database configuration
• FrankenPHP/Octane server settings
• Production-oriented cache and session settings
• Application name: "FlowTODO"

Deployment

GitHub Actions workflow triggers on release publication and pushes to gitgud.foo/thegrind/laravel-base registry with both latest and version tags.