cloud-apache-container/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Cloud Apache Container (CAC) is a Docker-based PHP web hosting environment that supports multiple PHP versions (7.4 through 8.4) with Apache, designed for both local development and production deployment.

Common Development Commands

Local Development Setup

# Quick start with automated setup (creates helper scripts)
./local-dev.sh -n local-dev

# With specific PHP version
./local-dev.sh -n myproject -a 84  # PHP 8.4

# Helper scripts created by local-dev.sh:
./instance_start    # Start container
./instance_stop     # Stop container
./instance_logs     # Tail Apache logs
./instance_db_info  # Show MySQL credentials

Building and Testing

# Build container locally
docker build -t cac:latest .

# Build with specific PHP version
docker build --build-arg PHP_VER=83 -t cac:php83 .

# Run container manually
docker run -d -p 80:80 -p 443:443 \
  -e PHPVER=83 -e environment=DEV \
  -e uid=$(id -u) -e user=$(whoami) -e domain=localhost \
  -v"$(pwd)/user":/home/$(whoami) \
  --name test-container cac:latest

Server Deployment

• Production git directory: /root/whp
• After git pull, sync web files: rsync -av web-files/ /docker/whp/web/

Architecture and Key Components

Directory Structure

• /scripts/ - Container setup scripts (entrypoint, PHP installers, vhost creation)
• /config/ - Apache and PHP configuration files
• /web-files/ - Default web content (ping endpoint)
• /.gitea/workflows/ - CI/CD pipeline for multi-PHP version builds

Container Behavior

1. Entrypoint Flow (scripts/entrypoint.sh):

   • Creates user with specified UID
   • Sets up directory structure
   • Configures Apache vhost based on environment variables
   • In DEV mode: starts MariaDB and Memcached
   • Starts Apache and PHP-FPM

2. Environment Modes:

   • DEV (environment=DEV): Local database, memcached, automatic backups
   • PROD (default): Expects external database/cache services

3. PHP Version Management:

   • Controlled via PHPVER environment variable (74, 80, 81, 82, 83, 84)
   • Each version has dedicated install script in /scripts/
   • PHP-FPM configuration dynamically created based on version

Key Environment Variables

• uid (required): User ID for file permissions
• user (required): Username for container user
• domain (required): Primary domain for Apache vhost
• serveralias: Additional domains (comma-separated)
• PHPVER: PHP version to use (default: 83)
• environment: DEV or PROD mode

Important Technical Details

1. Health Check: Available at /ping endpoint
2. Logs Location: /home/$user/logs/apache/ and /home/$user/logs/php-fpm/
3. Database Backups (DEV mode): Every 15 minutes to /home/$user/_db_backups/
4. Log Rotation: Compress after 3 days, delete after 7 days
5. SSL: Self-signed certificate auto-generated, proper SSL configured
6. WordPress: WP-CLI pre-installed for WordPress development