weboccult/laravel-base

By weboccult

•Updated 24 days ago

Base image for laravel projects

Image

Languages & frameworks

667

Overview Tags

weboccult/laravel-base repository overview

⁠Laravel Docker

Production-ready Docker base image for Laravel applications — PHP 8.3, Nginx, Supervisor, and Redis, all on Alpine Linux.

Build one image, run it as any service: web server, queue worker, task scheduler, WebSocket server (Reverb), or high-performance app server (Octane) — controlled entirely by the container command.

⁠Features

PHP 8.3 FPM on Alpine Linux (~175 MB base image)
Nginx reverse proxy with security headers, gzip, and static file caching
OPcache + JIT enabled out of the box for production performance
Multi-mode entrypoint — single image serves web, queue, scheduler, cron, worker, or artisan
Supervisor support for running queue + scheduler in one container
Redis extension pre-installed (cache, sessions, queues)
Common PHP extensions: pdo_mysql, gd (freetype/jpeg/webp), intl, zip, bcmath, pcntl, mbstring, xml, exif
Composer 2 included for dependency installation
Health checks built into both Nginx and PHP-FPM
Security hardened: expose_php=Off, server_tokens off, hidden file blocking, sensitive path protection
Production caching: auto-caches config, routes, and views when APP_ENV=production
Docker best practices: multi-stage builds, .dockerignore, non-root process execution, proper signal handling

⁠Quick Start

⁠1. Build the base image

git clone https://github.com/aspect-suspended/laravel-docker.git
cd laravel-docker
docker build -t laravel-base .

⁠2. Use in your Laravel project

This repository does not include a Laravel application. It provides only the Docker infrastructure. You bring your own Laravel app.

Create a Dockerfile in your Laravel project root:

FROM laravel-base:latest AS build

WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --no-scripts --prefer-dist --optimize-autoloader

FROM laravel-base:latest

WORKDIR /app
COPY --from=build /app/vendor /app/vendor
COPY --chown=www-data:www-data . /app

RUN composer dump-autoload --optimize --no-dev \
    && php artisan package:discover --ansi

CMD ["web"]

⁠3. Run it

# Web server (Nginx + PHP-FPM)
docker run -p 80:80 my-laravel-app web

# Queue worker
docker run my-laravel-app queue

# Task scheduler
docker run my-laravel-app scheduler

# One-off artisan command
docker run --rm my-laravel-app artisan migrate --force

⁠Installation

⁠Option A: Quick setup with the example script

The example/setup.sh script automates the full workflow — it clones a fresh Laravel project (or your own repo), copies in the Docker files, builds images, and starts the stack:

# Clone this repo
git clone https://github.com/aspect-suspended/laravel-docker.git
cd laravel-docker

# Run the setup script (creates a fresh Laravel project in example/app/)
cd example
./setup.sh

# Or point it at your existing project
./setup.sh https://github.com/your-user/your-laravel-app.git
./setup.sh /path/to/local/laravel-project

# Start the stack
docker compose up -d

The setup script will:

Create (or clone) a Laravel project into example/app/
Copy the Dockerfile and .dockerignore templates into the app
Build the laravel-base image from this repo's root
Build the laravel-app image from the app directory
Generate an APP_KEY if one isn't set
Print instructions for starting the stack

⁠Option B: Manual integration into an existing project

# 1. Build the base image
git clone https://github.com/aspect-suspended/laravel-docker.git
cd laravel-docker
docker build -t laravel-base .

# 2. In your Laravel project, create a Dockerfile (see Quick Start above)

# 3. Build your app image
cd /path/to/your-laravel-app
docker build -t my-app .

# 4. Run
docker run -p 80:80 my-app web

Note: The Laravel framework is always installed externally (via composer create-project, git clone, or your existing project). This repo stays lightweight and framework-agnostic — it only provides the Docker base image and configuration.

⁠Architecture

                    +------------------+
                    |   laravel-base   |   <-- This repo (base image)
                    |  PHP 8.3 + Nginx |
                    |  + Supervisor    |
                    +--------+---------+
                             |
                    +--------+---------+
                    |  laravel-app     |   <-- Your app (extends base)
                    |  App code +      |
                    |  Composer deps   |
                    +--------+---------+
                             |
              +--------------+--------------+
              |              |              |
        +-----+----+  +-----+----+  +------+-----+
        |   web    |  |  queue   |  | scheduler  |
        | Nginx +  |  | artisan  |  | schedule:  |
        | PHP-FPM  |  | queue:   |  | run loop   |
        | port 80  |  | work     |  | (60s)      |
        +----------+  +----------+  +------------+

All three services run the same image — only the command differs.

⁠Entrypoint Modes

Command	Description
`web`	Starts Nginx + PHP-FPM (default)
`queue`	Starts a Laravel queue worker
`scheduler`	Runs `artisan schedule:run` in a 60-second loop
`cron`	Starts the system cron daemon
`worker`	Starts Supervisor managing queue + scheduler together
`artisan`	Runs any artisan command (e.g., `artisan migrate`)

⁠Configuration

⁠Environment Variables

Variable	Default	Description
`APP_ENV`	`production`	When `production`, caches config/routes/views on startup
`RUN_MIGRATIONS`	`false`	Set to `true` to auto-run migrations on container start
`QUEUE_NAME`	`default`	Queue name(s) for the worker
`QUEUE_TRIES`	`3`	Number of times to retry a failed job
`QUEUE_TIMEOUT`	`90`	Max seconds a job may run
`QUEUE_MAX_JOBS`	`1000`	Worker restarts after processing this many jobs
`QUEUE_MAX_TIME`	`3600`	Worker restarts after running this many seconds

⁠PHP Configuration

Key settings in docker/php/php.ini:

Setting	Value	Notes
`memory_limit`	`512M`	Adjust per workload
`upload_max_filesize`	`100M`	Matched with Nginx `client_max_body_size`
`opcache.jit`	`1255`	JIT tracing mode with 128 MB buffer
`opcache.validate_timestamps`	`0`	Files never rechecked — deploy = restart
`expose_php`	`Off`	Hides PHP version from response headers

⁠PHP-FPM Pool

Key settings in docker/php/php-fpm.conf:

Setting	Value	Notes
`pm`	`dynamic`	Scales workers between min/max
`pm.max_children`	`20`	~30 MB per child; tune for container memory
`pm.max_requests`	`1000`	Workers recycle to prevent memory leaks
`clear_env`	`no`	Docker env vars pass through to PHP

⁠Nginx

Security features in docker/nginx/:

server_tokens off — hides Nginx version
Security headers: X-Frame-Options, X-Content-Type-Options, X-XSS-Protection, Referrer-Policy
Blocks access to hidden files (.env, .git)
Blocks access to vendor/, storage/ directories
/health endpoint for load balancer probes
Static file caching with immutable headers

⁠Examples

The examples/⁠ directory contains ready-to-use Docker setups for common Laravel service patterns:

Example	Description
`basic/`⁠	Standard web + queue + scheduler + MySQL + Redis
`reverb/`⁠	Laravel Reverb WebSocket server
`octane/`⁠	Laravel Octane with Swoole/FrankenPHP
`docker-compose.yml`⁠	Full stack combining all services

See examples/README.md⁠ for detailed usage instructions.

⁠Full Stack Example

cd examples/basic
./setup.sh                # Clones Laravel, builds images
docker compose up -d      # Starts web, queue, scheduler, mysql, redis

⁠Project Structure

laravel-docker/
├── Dockerfile                          # Base image definition
├── .dockerignore                       # Build context exclusions
├── docker/
│   ├── entrypoint.sh                   # Multi-mode entrypoint script
│   ├── nginx/
│   │   ├── nginx.conf                  # Main Nginx config
│   │   └── default.conf                # Laravel vhost config
│   ├── php/
│   │   ├── php.ini                     # PHP production settings
│   │   └── php-fpm.conf                # FPM pool configuration
│   └── supervisor/
│       ├── supervisord.conf            # Supervisor main config
│       └── conf.d/
│           ├── queue-worker.conf       # Queue worker process
│           └── scheduler.conf          # Scheduler process
├── examples/
│   ├── basic/                          # Standard full-stack example
│   ├── reverb/                         # Laravel Reverb WebSocket example
│   ├── octane/                         # Laravel Octane example
│   └── docker-compose.yml             # Combined services compose
├── CONTRIBUTING.md
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
└── LICENSE

⁠Customization

⁠Adding PHP extensions

Extend the base image in your project's Dockerfile:

FROM laravel-base:latest

# Example: add PostgreSQL support
RUN apk add --no-cache postgresql-dev \
    && docker-php-ext-install pdo_pgsql

⁠Overriding Nginx config

FROM laravel-base:latest
COPY my-nginx.conf /etc/nginx/http.d/default.conf

⁠Overriding PHP settings

FROM laravel-base:latest
COPY my-php.ini /usr/local/etc/php/conf.d/99-custom.ini

⁠Requirements

Docker 20.10+
Docker Compose v2 (for the examples)

⁠Contributing

Contributions are welcome. Please read CONTRIBUTING.md⁠ before submitting a pull request.

⁠Code of Conduct

This project follows the Contributor Covenant Code of Conduct⁠. By participating, you agree to uphold this code.

⁠License

This project is licensed under the MIT License. See LICENSE⁠ for details.

Tag summary

Recent tags

Content type

Image

Digest

sha256:b3a4d0af2…

Size

211.1 MB

Last updated

6 months ago

docker pull weboccult/laravel-base