kariricode/php-api-stack

By kariricode

•Updated 10 months ago

Production-ready multi-stage Docker stack with PHP-FPM, Nginx, Redis, Composer, and Symfony CLI

Image

Languages & frameworks

Developer tools

3.1K

Overview Tags

kariricode/php-api-stack repository overview

⁠KaririCode/php-api-stack

Production-ready PHP API Stack image built on Alpine Linux with Nginx + PHP-FPM + Redis. Secured, fast, and fully configurable via environment variables — ideal for modern APIs, web applications, and microservices.

⁠🔗 Official Links

Docker Hub: https://hub.docker.com/r/kariricode/php-api-stack⁠
GitHub Repository: https://github.com/kariricode/php-api-stack⁠
Documentation: Full guides in GitHub repository⁠
Official Site: https://kariricode.org/⁠
KaririCode Framework: https://github.com/KaririCode-Framework⁠

⁠✨ Highlights

⁠Core Stack

Complete Integration: Nginx 1.27.3 + PHP-FPM 8.4.13 + Redis 7.2.11
Alpine Linux 3.21: Minimal footprint (~225MB production, ~244MB dev)
Multi-platform: Native support for amd64 and arm64

⁠Performance

OPcache + JIT: Tracing mode enabled by default for maximum performance
Optimized Configuration: Tuned Nginx/PHP-FPM with Unix socket communication
FastCGI Cache: Built-in for accelerated response times
Static Assets: Direct Nginx serving with aggressive caching

⁠Security

Non-root Services: All services run as unprivileged users
Hardened Defaults: Security headers (CSP, HSTS, X-Frame-Options)
Rate Limiting: Built-in protection against abuse
Regular Updates: Automated security patches and vulnerability scanning

⁠Developer Experience

100% Configurable: All settings via environment variables
Three Specialized Makefiles: Build, Docker Hub, and Compose operations (50+ commands)
Comprehensive Health Checks: Simple and detailed endpoints for monitoring
CI/CD Ready: GitHub Actions workflows and automated testing
Development Image: Includes Xdebug 3.4.6 and Symfony CLI 5.15.1

⁠🚀 Quick Start

⁠30-Second Demo

Pull and run the demo page:

docker pull kariricode/php-api-stack:latest
docker run -d -p 8080:80 --name my-app kariricode/php-api-stack:latest

# Open: http://localhost:8080

You'll see a comprehensive status page showing PHP version, loaded extensions, OPcache statistics, Redis connectivity, and system resources.

⁠With Your Application

docker run -d \
  -p 8080:80 \
  --name my-app \
  -e APP_ENV=production \
  -e PHP_MEMORY_LIMIT=512M \
  -e PHP_OPCACHE_VALIDATE_TIMESTAMPS=0 \
  -v $(pwd)/app:/var/www/html:ro \
  kariricode/php-api-stack:latest

Important: Your application's public entry point must be at /var/www/html/public/index.php (Symfony/Laravel standard).

⁠🐳 Docker Compose

⁠Basic Setup

Create docker-compose.yml:

version: '3.9'

services:
  app:
    image: kariricode/php-api-stack:latest
    container_name: my-app
    ports:
      - "8080:80"
    environment:
      APP_ENV: production
      PHP_MEMORY_LIMIT: 512M
      PHP_FPM_PM_MAX_CHILDREN: 100
      REDIS_HOST: 127.0.0.1  # Using internal Redis
    volumes:
      - ./app:/var/www/html:ro
      - ./logs:/var/log
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s
      timeout: 3s
      retries: 3
    restart: unless-stopped

⁠With External Database

version: '3.9'

services:
  app:
    image: kariricode/php-api-stack:latest
    container_name: my-app
    ports:
      - "8080:80"
    environment:
      APP_ENV: production
      DATABASE_URL: mysql://user:pass@db:3306/myapp
      REDIS_HOST: 127.0.0.1  # Internal Redis
    volumes:
      - ./app:/var/www/html:ro
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s
    restart: unless-stopped
    networks:
      - app-network

  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: myapp
      MYSQL_USER: user
      MYSQL_PASSWORD: pass
    volumes:
      - db-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - app-network

volumes:
  db-data:

networks:
  app-network:
    driver: bridge

Note about Redis: This image includes an internal Redis instance on 127.0.0.1:6379. For external Redis, create a separate service and set REDIS_HOST to the service name.

Start services:

docker compose up -d
docker compose logs -f
docker compose ps

⁠🏷️ Available Tags

Tag	Description	Size	Use Case
`latest`	Latest stable release	~225MB	General use
`1.5.0`	Specific version	~225MB	Production (pinned)
`1.5`	Latest patch in v1.5.x	~225MB	Auto-patch updates
`1`	Latest minor in v1.x.x	~225MB	Auto-minor updates
`dev`	Development build	~244MB	Local development with Xdebug
`test`	With comprehensive health checks	~216MB	Testing/monitoring

⁠Tagging Strategy

Production: Always pin to specific versions (1.5.0) for reproducibility
Development: Use dev tag for debugging capabilities
Staging: Use minor version tags (1.5) for automatic patch updates
Never use latest in production

Pull a specific tag:

docker pull kariricode/php-api-stack:1.5.0
docker pull kariricode/php-api-stack:dev

⁠⚙️ Configuration

All configuration is done via environment variables. The image supports 100+ configuration options covering PHP, PHP-FPM, Nginx, Redis, and application settings.

⁠Essential Variables

# Application
APP_ENV=production                      # production|development|test
APP_DEBUG=false                         # Enable debug mode
APP_NAME=my-application                 # Application name

# PHP Runtime
PHP_MEMORY_LIMIT=512M                   # Memory per request
PHP_MAX_EXECUTION_TIME=60               # Script timeout
PHP_UPLOAD_MAX_FILESIZE=100M            # Max upload size
PHP_POST_MAX_SIZE=100M                  # Max POST size
PHP_DATE_TIMEZONE=UTC                   # Timezone

# PHP-FPM
PHP_FPM_PM=static                       # static|dynamic|ondemand
PHP_FPM_PM_MAX_CHILDREN=100             # Worker processes

# OPcache
PHP_OPCACHE_ENABLE=1                    # Enable OPcache
PHP_OPCACHE_MEMORY=256                  # OPcache memory (MB)
PHP_OPCACHE_VALIDATE_TIMESTAMPS=0       # 0 for prod, 1 for dev
PHP_OPCACHE_JIT=tracing                 # JIT mode

# Nginx
NGINX_WORKER_PROCESSES=auto             # auto = CPU cores
NGINX_CLIENT_MAX_BODY_SIZE=100M         # Max request size

# Redis (Internal)
REDIS_HOST=127.0.0.1                    # Internal Redis (standalone)
REDIS_PASSWORD=                         # Optional password

Complete reference: See .env.example⁠ in the repository.

⁠Configuration Examples

⁠High Performance Setup

docker run -d \
  -p 80:80 \
  -e PHP_MEMORY_LIMIT=512M \
  -e PHP_FPM_PM=static \
  -e PHP_FPM_PM_MAX_CHILDREN=200 \
  -e PHP_OPCACHE_MEMORY=512 \
  -e PHP_OPCACHE_VALIDATE_TIMESTAMPS=0 \
  -e PHP_OPCACHE_JIT=tracing \
  -e NGINX_WORKER_CONNECTIONS=4096 \
  -v $(pwd)/app:/var/www/html:ro \
  kariricode/php-api-stack:latest

⁠Memory-Constrained Environment

docker run -d \
  -p 80:80 \
  --memory="512m" \
  -e PHP_MEMORY_LIMIT=256M \
  -e PHP_FPM_PM=dynamic \
  -e PHP_FPM_PM_MAX_CHILDREN=25 \
  -e PHP_OPCACHE_MEMORY=128 \
  -v $(pwd)/app:/var/www/html:ro \
  kariricode/php-api-stack:latest

⁠📊 Stack Components

Component	Version	Purpose
PHP-FPM	8.4.13	PHP processing with optimized pool
Nginx	1.27.3	High-performance web server
Redis	7.2.11	Cache and session management
Alpine Linux	3.21	Minimal base image
Composer	2.8.12	PHP dependency manager
Symfony CLI	5.15.1	Symfony tools (dev only)
Xdebug	3.4.6	PHP debugger (dev only)

⁠PHP Extensions

Core Extensions (Pre-installed):

pdo, pdo_mysql, opcache, intl, zip, bcmath, gd, mbstring, xml, sockets

PECL Extensions (Pre-installed):

redis (6.1.0), apcu (5.1.24), uuid (1.2.1), imagick (3.7.0), amqp (2.1.2)

Built-in Extensions (Always available):

json, curl, fileinfo, ctype, iconv, session, tokenizer, filter, hash, openssl

⁠🏥 Health Checks

⁠Simple Health Check

Lightweight endpoint for load balancers and orchestrators:

curl http://localhost:8080/health
# Response: healthy

HTTP 200 if healthy, 503 if unhealthy.

⁠Comprehensive Health Check

Detailed diagnostics with component-level checks:

curl http://localhost:8080/health.php | jq

Returns JSON with:

Overall status (healthy/degraded/unhealthy)
PHP runtime details (version, memory, extensions)
OPcache statistics (hit rate, memory, JIT status)
Redis connectivity (latency, memory, persistence)
System resources (disk, CPU, memory)
Application directories (permissions, accessibility)

Docker Healthcheck:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost/health"]
  interval: 30s
  timeout: 3s
  retries: 3
  start_period: 10s

Kubernetes Probes:

livenessProbe:
  httpGet:
    path: /health
    port: 80
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health.php
    port: 80
  initialDelaySeconds: 10
  periodSeconds: 5

⁠🎭 Framework Integration

⁠Symfony

docker run -d \
  -p 8080:80 \
  -e APP_ENV=prod \
  -e APP_SECRET=$(openssl rand -hex 16) \
  -e DATABASE_URL=mysql://user:pass@db:3306/symfony \
  -v $(pwd):/var/www/html:ro \
  kariricode/php-api-stack:latest

⁠Laravel

docker run -d \
  -p 8080:80 \
  -e APP_ENV=production \
  -e APP_KEY=base64:your-key-here \
  -e DB_CONNECTION=mysql \
  -e DB_HOST=db \
  -e DB_DATABASE=laravel \
  -v $(pwd):/var/www/html:ro \
  kariricode/php-api-stack:latest

⁠Custom PHP App

docker run -d \
  -p 8080:80 \
  -e APP_ENV=production \
  -v $(pwd)/my-app:/var/www/html:ro \
  kariricode/php-api-stack:latest

Directory Structure: Your app must have public/index.php as the entry point.

⁠🔐 Security Features

⁠Built-in Security

✅ Non-root Services: All services run as unprivileged users (www-data, nginx, redis)
✅ Security Headers: X-Frame-Options, X-Content-Type-Options, CSP, HSTS
✅ Rate Limiting: 10 req/s (general), 100 req/s (API endpoints)
✅ Disabled Functions: Dangerous PHP functions blocked
✅ Open Basedir: Restricted to /var/www/html and /tmp
✅ Hidden Tokens: Server version and PHP version hidden

⁠Best Practices

Always use specific version tags in production
Mount application code as read-only (:ro)
Store secrets in environment variables
Enable HTTPS via reverse proxy (Nginx, Traefik, etc.)
Regularly update to latest patch versions
Use vulnerability scanning (Trivy included in CI/CD)

⁠🧪 Testing & Development

⁠Development Image

The dev tag includes additional tools for local development:

docker run -d \
  -p 8001:80 \
  -p 9003:9003 \
  -e APP_ENV=development \
  -e APP_DEBUG=true \
  -e PHP_DISPLAY_ERRORS=On \
  -e XDEBUG_ENABLE=1 \
  -v $(pwd)/app:/var/www/html \
  kariricode/php-api-stack:dev

Includes:

Xdebug 3.4.6 (configurable)
Symfony CLI 5.15.1
Extended error reporting
File change detection (OPcache revalidation)

⁠Running Tests

# Quick version check
docker run --rm kariricode/php-api-stack:latest php -v

# Full test suite
docker run --rm kariricode/php-api-stack:test /usr/local/bin/health-check.sh

⁠🛠 Makefile Commands

The repository includes three specialized Makefiles with 50+ commands:

⁠Main Makefile (Build & Runtime)

make build              # Build production image
make build-dev          # Build dev image
make run                # Run production container
make run-dev            # Run dev container
make test               # Run test suite
make lint               # Lint Dockerfile
make scan               # Security scan

⁠Makefile.dockerhub (Publishing)

make hub-help           # Show Docker Hub commands
make version            # Show current version
make bump-patch         # Bump patch version
make tag-production     # Tag production image
make push-production    # Push to Docker Hub
make release-production # Full release pipeline

⁠Makefile.compose (Orchestration)

make compose-help       # Show Compose commands
make compose-up         # Start services
make compose-logs       # View logs
make compose-shell      # Access container

Get the source: https://github.com/kariricode/php-api-stack⁠

⁠🐛 Troubleshooting

⁠Container Won't Start

# Check logs
docker logs <container-name>

# Common causes:
# - Port already in use → Change port: -p 8081:80
# - Volume permissions → Fix: chmod -R 755 app/
# - Memory limits → Increase: --memory="1g"

⁠502 Bad Gateway

# Check PHP-FPM
docker exec <container> ps aux | grep php-fpm

# Check logs
docker exec <container> tail -f /var/log/php/fpm-error.log
docker exec <container> tail -f /var/log/nginx/error.log

# Restart PHP-FPM
docker exec <container> kill -USR2 $(cat /var/run/php/php-fpm.pid)

⁠Redis Connection Issues

# Check Redis (internal)
docker exec <container> redis-cli -h 127.0.0.1 ping
# Should return: PONG

# Check REDIS_HOST variable
docker exec <container> env | grep REDIS_HOST
# Should be: 127.0.0.1 (standalone) or redis (compose)

# Test with password (if configured)
docker exec <container> redis-cli -h 127.0.0.1 -a "password" ping

⁠Slow Performance

# Check OPcache hit rate (should be >95%)
docker exec <container> php -r "
\$stats = opcache_get_status()['opcache_statistics'];
echo 'Hit Rate: ' . \$stats['opcache_hit_rate'] . '%' . PHP_EOL;
"

# Check resource usage
docker stats <container>

# Solutions:
# - Increase OPcache memory: -e PHP_OPCACHE_MEMORY=512
# - Increase FPM workers: -e PHP_FPM_PM_MAX_CHILDREN=100
# - Add container resources: --memory="2g" --cpus="4"

Complete troubleshooting guide: IMAGE_USAGE_GUIDE.md⁠

⁠📚 Documentation

Document	Description
README.md⁠	Project overview and quick start
IMAGE_USAGE_GUIDE.md⁠	Complete usage guide for end users
DOCKER_COMPOSE_GUIDE.md⁠	Docker Compose orchestration
TESTING.md⁠	Testing procedures for maintainers

⁠🔄 Version History

⁠v1.5.0 (2025-10-24) - Latest

Docker Hub Integration:

Fixed hub-check command display bug
Simplified dev tagging: only dev tag (removed dev-X.Y.Z)
Fixed version bump commands (bump-patch, bump-minor, bump-major)
Improved hub-check output with checkmarks (✓/✗)
Added comprehensive Docker Hub utilities

Breaking Changes:

Dev versioned tags (dev-X.Y.Z) are no longer created

⁠v1.4.5 (2025-10-24)

Build System:

Fixed PHP extension quoting in Makefile
Secure .env parsing to prevent command execution
Proper escaping for build args

Redis Integration:

Automatic REDIS_HOST override for standalone containers
Smart DNS fallback in health checks
Documentation improvements

Dockerfile:

Fixed OPcache validation (Zend extension check)
Added util-linux for UUID extension
Fixed shellcheck errors

⁠v1.4.3 (2025-10-20)

Refactored Makefile with 50+ organized commands
Enhanced development workflow
Improved health check monitoring
Updated documentation

⁠v1.2.1 (2025-10-18)

Added comprehensive Makefile
Docker Compose integration
Multiple service profiles
Enhanced health checks

⁠v1.2.0 (2025-10-15)

PHP 8.4, Nginx 1.27.3, Redis 7.2
OPcache + JIT optimization
Socket-based PHP-FPM
Environment variable configuration

Full changelog: GitHub Releases⁠

This image is part of the KaririCode ecosystem:

⁠KaririCode Framework

Modern PHP framework with advanced features:

Repository: KaririCode-Framework⁠
30+ Components: DI, Router, Auth, Cache, EventDispatcher, etc.
ARFA Architecture: Adaptive Reactive Flow Architecture

⁠KaririCode DevKit

Development environment automation:

Repository: kariricode/devkit⁠
Features: Docker, Compose, quality tools, CI/CD
Integration: Uses this Docker image

⁠🤝 Contributing

Contributions are welcome! Please:

Fork the repository: https://github.com/kariricode/php-api-stack⁠
Create a feature branch
Make your changes
Submit a Pull Request

Standards:

Follow PSR-12 for PHP
Use Conventional Commits
Add tests for new features
Update documentation

⁠📄 License

This project is licensed under the MIT License.
See LICENSE⁠ in the repository.

⁠🙌 Support

Issues: GitHub Issues⁠
Discussions: GitHub Discussions⁠
Docker Hub: kariricode/php-api-stack⁠

Made with 💚 by KaririCode⁠

Tag summary

Recent tags

Content type