Javier Feliz
3d7683c8ac
All checks were successful
Build & Push Docker Image to Registry / build (release) Successful in 5m1s
96 lines
3.4 KiB
Markdown
96 lines
3.4 KiB
Markdown
# 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. |