# 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
```bash
docker build -t laravel-base .
```

### Running a Container
```bash
# 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
```dockerfile
FROM gitgud.foo/thegrind/laravel-base:latest
COPY ./hook.sh /app/hook.sh
# Your application code and additional setup
```

### Example hook.sh
```bash
#!/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
```dockerfile
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.