LEMP Docker Overview

Relevant source files

• .github/workflows/base-images.yml
• README.md

This document provides a comprehensive introduction to the lemp-docker repository, a Docker-based solution for deploying LNMP (Linux, Nginx, MariaDB, PHP-FPM) stack applications. The document covers the image ecosystem, variant matrix, high-level architecture, and core concepts needed to understand and use these Docker images effectively.

For specific configuration details and environment variables, see Configuration Reference. For container internals and service topology, see Container Architecture. For build system details, see Build System.

Sources: README.md1-13

What is LNMP/LEMP

The repository provides Docker images for an LNMP stack, commonly referred to as LEMP:

Component	Description	Role
Linux	Alpine Linux base	Operating system foundation
Nginx	Web server	HTTP request handling, static file serving
MariaDB	Database server	Data persistence and management
PHP-FPM	PHP FastCGI Process Manager	Dynamic content execution

The acronym "LEMP" uses "E" for "Engine-X" (Nginx pronunciation). Both terms refer to the same stack. The images are published under both namespaces: fbraz3/lnmp and fbraz3/lemp.

Sources: README.md5-7

Image Ecosystem and Inheritance

The LNMP images are built on a modular ecosystem of base images from the fbraz3 namespace, providing a layered architecture for maintainability and feature reuse.

Base Image Inheritance Chain

Sources: README.md11-13 README.md231-248

Inherited Features

From the upstream base images, all LNMP images inherit:

Feature	Source Image	Description
Email sending	php-base-docker	SMTP configuration for PHP mail() function
PHP directive management	php-fpm-docker	Environment variable-based PHP configuration
Cronjob support	php-fpm-docker	Cron scheduling via /cronfile mount
Nginx + PHP-FPM integration	php-nginx	Optimized web server and application runtime

Sources: README.md231-248

Image Variant Matrix

The repository produces a matrix of images across three dimensions: PHP version, flavor, and environment.

Dimension 1: PHP Versions

The build system supports 11 PHP versions spanning from legacy to modern releases:

Version	Support Status	Notes
PHP 5.6	Legacy	End of life
PHP 7.0 - 7.4	Legacy	End of life
PHP 8.0 - 8.4	Active	PHP 8.4 is latest

Sources: .github/workflows/base-images.yml14-36

Dimension 2: Flavors

Flavor	Description	Use Case
Vanilla	Base LNMP stack with no framework	General-purpose PHP applications
Phalcon	Includes Phalcon PHP framework	Applications using Phalcon framework

Sources: README.md80-86

Dimension 3: Environments

The critical architectural distinction is between development and production variants:

Aspect	Development (-dev)	Production (no suffix)
phpMyAdmin	✓ Accessible at /pma/	✗ Not installed
Database Port	✓ Exposed on 3306	✗ Internal only
Root Password	✗ Empty (no password)	✓ Required via MYSQL_ROOT_PASSWORD
Security	✗ Minimal (convenience first)	✓ Hardened (security first)
Custom SQL	✗ Not supported	✓ Executed from /sql-scripts
App Provisioning	✗ Manual setup	✓ Automated via env vars

Sources: README.md34-57 README.md187-202

Complete Tag Schema

The tagging scheme follows this pattern:

fbraz3/lnmp:{php_version}[-{flavor}][-{environment}]

Tag Pattern	Example	Description
{version}	8.4, 8.3, 7.4	Production vanilla
{version}-dev	8.4-dev, 8.3-dev	Development vanilla
{version}-phalcon	8.4-phalcon	Production Phalcon
{version}-phalcon-dev	8.4-phalcon-dev	Development Phalcon
latest	latest	PHP 8.4 production vanilla
latest-dev	latest-dev	PHP 8.4 development vanilla
latest-phalcon	latest-phalcon	PHP 8.4 production Phalcon
latest-phalcon-dev	latest-phalcon-dev	PHP 8.4 development Phalcon

All tags are available under both fbraz3/lnmp and fbraz3/lemp namespaces.

Sources: README.md58-79 .github/workflows/base-images.yml206-227

Architecture Support

All images are built as multi-architecture manifests supporting:

• linux/amd64 (x86-64)
• linux/arm64 (ARM 64-bit, including Apple Silicon)

Docker automatically selects the appropriate architecture for the host system.

Sources: README.md76-78 .github/workflows/base-images.yml42-46 .github/workflows/base-images.yml198

Runtime Architecture

The images package a complete LNMP stack within a single container, orchestrated by process supervision.

Service Topology

Sources: README.md88-139 High-Level Diagram 3

Key Runtime Characteristics

1. Single-Container Design: All services run in one container, simplifying deployment and networking
2. Process Supervision: Monit monitors MariaDB and restarts it if it crashes
3. Initialization Order: Database initialization occurs before service startup
4. Health Monitoring: Docker health checks validate Nginx and MariaDB status every 30 seconds
5. Volume Persistence: Database data persists across container restarts via named volume

Sources: High-Level Diagram 3

Build Pipeline

The repository uses GitHub Actions to automate image building, testing, and publication.

Workflow Architecture

Build Matrix

The matrix produces 44 images per workflow (vanilla and Phalcon each):

• 11 PHP versions × 2 environments (dev/prod) × 2 architectures (amd64/arm64) = 44 single-arch images
• These combine into 22 multi-arch manifests per workflow
• Total: 88 images published weekly across both workflows

Sources: .github/workflows/base-images.yml8-36 High-Level Diagram 1, High-Level Diagram 5

Testing Strategy

Each build includes automated testing before publication:

Development Image Tests (.github/workflows/base-images.yml63-79):

• ✓ MariaDB process running (grep mariadbd)
• ✓ Database responds to ping (mysqladmin ping)
• ✓ Port 3306 accessible (telnet 127.0.0.1 3306)
• ✓ Nginx serves application (curl http://127.0.0.1/)
• ✓ phpMyAdmin accessible (curl http://127.0.0.1/pma/)
• ✓ Monit active (monit summary)

Production Image Tests (.github/workflows/base-images.yml96-116):

• ✓ MariaDB with authentication (mysqladmin -u root -p...)
• ✓ Application served
• ✗ phpMyAdmin NOT accessible (! curl -f /pma/)
• ✓ App database created (USE test_app_db)
• ✓ App user created with permissions
• ✓ Monit active

Sources: .github/workflows/base-images.yml63-116 High-Level Diagram 5

Core Features

Environment-Based Configuration

Production images support application provisioning via environment variables:

Variable	Purpose	Example
MYSQL_ROOT_PASSWORD	Required root password	securePass123!
MYSQL_APP_DATABASE	Auto-create application database	my_app
MYSQL_APP_USER	Auto-create application user	app_user
MYSQL_APP_USER_PASSWD	Application user password	userPass123!

The production entrypoint script validates passwords and fails container startup if using defaults, enforcing security.

Sources: README.md203-226

Custom SQL Initialization

Production images execute custom SQL scripts during first startup:

1. Mount directory to /sql-scripts in container
2. Place .sql files in the directory
3. Scripts execute in alphabetical order with root privileges
4. Execution occurs only on first startup (when database is initialized)

Example directory structure:

project/
├── sql-scripts/
│   ├── 01-schema.sql
│   ├── 02-seed-data.sql
│   └── 03-permissions.sql
└── docker-compose.yml

Sources: README.md141-186

Inherited Features

From upstream fbraz3 images:

• PHP Directive Management: Configure PHP settings via environment variables (e.g., PHP__memory_limit=256M)
• Cronjob Support: Mount cron schedule to /cronfile for automated task execution
• Email Configuration: Configure SMTP settings for PHP mail() function

Sources: README.md231-248

Use Cases

Scenario	Recommended Image	Rationale
Local development	fbraz3/lnmp:8.4-dev	phpMyAdmin included, no password required
CI/CD testing	fbraz3/lnmp:8.4-dev	Fast startup, no configuration needed
Production deployment	fbraz3/lnmp:8.4	Secure by default, mandatory authentication
Phalcon applications	fbraz3/lnmp:8.4-phalcon	Framework pre-installed and configured
Legacy PHP support	fbraz3/lnmp:5.6	Support for PHP 5.6+ applications
ARM-based hosts	Any tag	Multi-arch support (including Apple Silicon)

Critical Warning: Never use -dev images in production. They have no root password, expose database ports, and include debugging tools.

Sources: README.md187-202

Quick Start Examples

For practical usage examples and docker-compose configurations, see Quick Start Guide.

For detailed configuration options and environment variables, see Configuration Reference.

For internal container architecture and service interactions, see Container Architecture.

---

Complete Sources:

• README.md1-267
• .github/workflows/base-images.yml1-228
• High-Level System Architecture Diagrams 1-5