Skip to content

installation.md

Latest commit

 

History

History
320 lines (240 loc) · 6.35 KB

installation.md

File metadata and controls

320 lines (240 loc) · 6.35 KB
Raw
title Installation
description Install Cbox PHP Base Images with Docker, Docker Compose, or Kubernetes
weight 2

Installation

Cbox images are available from GitHub Container Registry (ghcr.io). No authentication required for pulling.

Quick Install

Docker CLI

# Pull the recommended image
docker pull ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm

# Verify installation
docker run --rm ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm php -v

Expected output:

PHP 8.4.x (cli) (built: ...)
Copyright (c) The PHP Group
Zend Engine v4.4.x, Copyright (c) Zend Technologies
    with Zend OPcache v8.4.x, Copyright (c), by Zend Technologies

Docker Compose

# docker-compose.yml
services:
  app:
    image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm
    ports:
      - "8000:80"
    volumes:
      - .:/var/www/html
docker compose up -d
open http://localhost:8000

Available Images

Multi-Service (Recommended)

PHP-FPM + Nginx in one container. Best for most applications.

# Standard tier (DEFAULT)
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm

# Slim tier (APIs, microservices)
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm-slim

Development Editions

Include Xdebug and SPX profiler:

ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm-dev

Single-Process (Microservices)

For Kubernetes or when you need separate scaling:

# PHP-FPM only
ghcr.io/cboxdk/php-baseimages/php-fpm:8.4-bookworm

# PHP CLI only
ghcr.io/cboxdk/php-baseimages/php-cli:8.4-bookworm

# Nginx only
ghcr.io/cboxdk/php-baseimages/nginx:bookworm

PHP Version Support

Version Status Recommended
PHP 8.5 Active Yes
PHP 8.4 Active Yes
PHP 8.3 Active Yes
PHP 8.2 EOL Dec 2025 Upgrade recommended 
# PHP 8.5 (latest)
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-bookworm

# PHP 8.4
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm

# PHP 8.3
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.3-bookworm

# PHP 8.2 (EOL)
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.2-bookworm

Tagging Strategy

Rolling Tags (Recommended)

Updated weekly with security patches:

php-fpm-nginx:8.4-bookworm       # Latest 8.4 (standard tier)
php-fpm-nginx:8.4-bookworm-slim  # Latest 8.4 (slim tier)

Immutable Tags

For reproducible builds:

php-fpm-nginx:8.4-bookworm-sha256:abc123...

Installation Methods

Method 1: Direct Docker Run

docker run -d \
  --name myapp \
  -p 8000:80 \
  -v $(pwd):/var/www/html \
  ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm

Method 2: Docker Compose (Recommended)

# docker-compose.yml
services:
  app:
    image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm
    ports:
      - "8000:80"
    volumes:
      - .:/var/www/html
    environment:
      PHP_MEMORY_LIMIT: 256M

Method 3: Custom Dockerfile

FROM ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm

# Add custom extensions
RUN apt-get update && apt-get install -y $PHPIZE_DEPS \
    && pecl install swoole \
    && docker-php-ext-enable swoole \
    && apt-get purge -y --auto-remove $PHPIZE_DEPS \
    && rm -rf /var/lib/apt/lists/*

# Copy application
COPY . /var/www/html

Method 4: Kubernetes

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
        - name: app
          image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm
          ports:
            - containerPort: 80
          env:
            - name: PHP_MEMORY_LIMIT
              value: "512M"

Method 5: CI/CD Pipeline

GitHub Actions:

# .github/workflows/deploy.yml
jobs:
  build:
    runs-on: ubuntu-latest  # Use your CI provider's Linux runner
    steps:
      - uses: actions/checkout@v4

      - name: Build image
        run: |
          docker build -t myapp:${{ github.sha }} .

      - name: Push to registry
        run: |
          docker push myapp:${{ github.sha }}

GitLab CI:

# .gitlab-ci.yml
build:
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

Verify Installation

Check PHP Version and Extensions

# PHP version
docker run --rm ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm php -v

# Installed extensions
docker run --rm ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm php -m

# Specific extension
docker run --rm ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm php -m | grep redis

Check Services

# Start container
docker run -d --name test ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm

# Check processes
docker exec test ps aux

# Check health
docker exec test /usr/local/bin/healthcheck.sh

# Cleanup
docker rm -f test

Test Web Server

# Create test file
echo '<?php phpinfo();' > index.php

# Run container
docker run -d --name test -p 8000:80 -v $(pwd):/var/www/html/public \
  ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm

# Test
curl http://localhost:8000

# Cleanup
docker rm -f test
rm index.php

Troubleshooting Installation

Image Not Found

# Error: manifest unknown
docker pull ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm

# Solution: Check image name spelling
# Correct: php-fpm-nginx (with hyphens)
# Wrong: php_fpm_nginx, phpfpmnginx

Permission Denied

# Error: permission denied
# Solution: Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

Architecture Mismatch

# Error: no matching manifest for linux/arm64
# Solution: Cbox supports both architectures
# Check your platform
docker info | grep Architecture

# Force platform if needed
docker pull --platform linux/amd64 ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm

Next Steps