added ai files

Rebuild on the official PHP image instead of Sury's repo on bare Debian.
Fixes surfaced along the way: missing pkg-config/libonig-dev broke the
zip/mbstring extension builds, purging libzip-dev also auto-removed the
libzip5 runtime lib the compiled zip.so needs, phpredis needed bumping to
6.3.0 for PHP 8.5 header compatibility, and the php-fpm.conf listen
directive sed didn't match the commented-out default line so FPM never
created its unix socket, causing 503s from Apache's proxy_fcgi handler.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

000-default.conf

@@ -13,10 +13,11 @@
 
     # PHP-FPM handler
     <FilesMatch \.php$>
-        SetHandler "proxy:unix:/run/php/php8.5-fpm.sock|fcgi://localhost/"
+        SetHandler "proxy:unix:/run/php/php-fpm.sock|fcgi://localhost/"
     </FilesMatch>
 
     # Docker-friendly logging
     ErrorLog /proc/self/fd/2
     CustomLog /proc/self/fd/1 combined
+
 </VirtualHost>

AGENTS.md

@@ -0,0 +1,53 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents (e.g. opencode, DeepSeek-based agents) when working with code in this repository.
+
+## What this is
+
+CORXN is a Docker image definition (not an application) — a single `Dockerfile` built `FROM php:8.5.8-fpm-trixie` (official PHP image, Debian Trixie base) with Apache + Redis extension layered on top, intended as the base runtime for the [Novaconium PHP Framework](https://git.4lt.ca/4lt/novaconium). There is no application code here; the repo's output is the built Docker image `4lights/corxn`.
+
+## Key files
+
+- `Dockerfile` — builds the image: installs Apache via `apt`, builds PHP extensions (`mysqli`, `pdo_mysql`, `mbstring`, `zip` via `docker-php-ext-install`; `redis` via `pecl`) against the base image's pinned PHP 8.5.8 (`xml` and `curl` are already built into the base image, so they aren't reinstalled), enables `mpm_event` + PHP-FPM via `proxy_fcgi`, sets security headers, compression, keepalive, and MPM tuning, and configures logrotate. PHP custom config is loaded from `/php`, layered in front of the base image's default `conf.d` via `PHP_INI_SCAN_DIR`.
+- `000-default.conf` — Apache vhost, copied into the image. `DocumentRoot` is `/data/public`; PHP requests are proxied to the PHP-FPM unix socket at `/run/php/php-fpm.sock`. Logs go to stdout/stderr (`/proc/self/fd/1` and `2`) for Docker-friendly logging.
+- `php.ini` — custom PHP settings copied into the image at `/php/php.ini` (uploads, timezone `America/Vancouver`, OPcache tuned for production with `validate_timestamps=0`, sessions backed by Redis at `tcp://redis:6379`). Can be overridden at runtime by bind-mounting a different file to the same path.
+- `start.sh` — container entrypoint: starts `php-fpm` (daemonized) then runs `apachectl` in the foreground.
+- `docker-compose.yml` — sample compose stack showing the intended usage: `corxn` container + `redis` + `mariadb`, with `./test` (or an app checkout) mounted to `/data` so the app's `public/` dir is served.
+- `test/public` — a minimal PHP app used to sanity-check the built image (see Testing below).
+
+## Building and testing
+
+Build the image:
+```bash
+docker buildx build --no-cache -t 4lights/corxn:latest --load .
+```
+
+To bump the PHP version, change the base image tag in the `FROM` line (e.g. `php:8.5.9-fpm-trixie`) — the official image is versioned exactly, no separate pin mechanism needed.
+
+Test the build:
+```bash
+mkdir -p data/uploads && sudo chown -R 33:33 data/uploads && chmod 775 data/uploads
+docker compose up -d
+# Visit: http://localhost:8000/test.php
+# Verify: file upload works and green checkmarks appear
+```
+(UID 33 is `www-data` inside the container.)
+
+View logs: `docker logs corxn`
+
+## Publishing (requires explicit user confirmation before pushing)
+
+```bash
+sudo su
+docker buildx build --no-cache -t 4lights/corxn:8.5.8 -t 4lights/corxn:latest --load .
+docker login -u <username>
+docker push 4lights/corxn:8.5.8
+docker push 4lights/corxn:latest
+```
+
+## Architecture notes for changes
+
+- Any consuming app is expected to be mounted at `/data`, with its web-servable code under `/data/public` (matches `DocumentRoot` in `000-default.conf`).
+- PHP config changes belong in `php.ini` (image default) — downstream users override it by bind-mounting their own file over `/php/php.ini`, so avoid assuming values in `php.ini` are final.
+- Because `opcache.validate_timestamps=0`, PHP file changes require a container restart/FPM reload to take effect — relevant when iterating on `test/public` during image testing.
+- Sessions and app-level caching are expected to go through the `redis` service (session handler already wired to `tcp://redis:6379`); MariaDB is the expected DB backend (see `docker-compose.yml` env vars).

CLAUDE.md

@@ -0,0 +1,53 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+CORXN is a Docker image definition (not an application) — a single `Dockerfile` built `FROM php:8.5.8-fpm-trixie` (official PHP image, Debian Trixie base) with Apache + Redis extension layered on top, intended as the base runtime for the [Novaconium PHP Framework](https://git.4lt.ca/4lt/novaconium). There is no application code here; the repo's output is the built Docker image `4lights/corxn`.
+
+## Key files
+
+- `Dockerfile` — builds the image: installs Apache via `apt`, builds PHP extensions (`mysqli`, `pdo_mysql`, `mbstring`, `zip` via `docker-php-ext-install`; `redis` via `pecl`) against the base image's pinned PHP 8.5.8 (`xml` and `curl` are already built into the base image, so they aren't reinstalled), enables `mpm_event` + PHP-FPM via `proxy_fcgi`, sets security headers, compression, keepalive, and MPM tuning, and configures logrotate. PHP custom config is loaded from `/php`, layered in front of the base image's default `conf.d` via `PHP_INI_SCAN_DIR`.
+- `000-default.conf` — Apache vhost, copied into the image. `DocumentRoot` is `/data/public`; PHP requests are proxied to the PHP-FPM unix socket at `/run/php/php-fpm.sock`. Logs go to stdout/stderr (`/proc/self/fd/1` and `2`) for Docker-friendly logging.
+- `php.ini` — custom PHP settings copied into the image at `/php/php.ini` (uploads, timezone `America/Vancouver`, OPcache tuned for production with `validate_timestamps=0`, sessions backed by Redis at `tcp://redis:6379`). Can be overridden at runtime by bind-mounting a different file to the same path.
+- `start.sh` — container entrypoint: starts `php-fpm` (daemonized) then runs `apachectl` in the foreground.
+- `docker-compose.yml` — sample compose stack showing the intended usage: `corxn` container + `redis` + `mariadb`, with `./test` (or an app checkout) mounted to `/data` so the app's `public/` dir is served.
+- `test/public` — a minimal PHP app used to sanity-check the built image (see Testing below).
+
+## Building and testing
+
+Build the image:
+```bash
+docker buildx build --no-cache -t 4lights/corxn:latest --load .
+```
+
+To bump the PHP version, change the base image tag in the `FROM` line (e.g. `php:8.5.9-fpm-trixie`) — the official image is versioned exactly, no separate pin mechanism needed.
+
+Test the build:
+```bash
+mkdir -p data/uploads && sudo chown -R 33:33 data/uploads && chmod 775 data/uploads
+docker compose up -d
+# Visit: http://localhost:8000/test.php
+# Verify: file upload works and green checkmarks appear
+```
+(UID 33 is `www-data` inside the container.)
+
+View logs: `docker logs corxn`
+
+## Publishing (requires explicit user confirmation before pushing)
+
+```bash
+sudo su
+docker buildx build --no-cache -t 4lights/corxn:8.5.8 -t 4lights/corxn:latest --load .
+docker login -u <username>
+docker push 4lights/corxn:8.5.8
+docker push 4lights/corxn:latest
+```
+
+## Architecture notes for changes
+
+- Any consuming app is expected to be mounted at `/data`, with its web-servable code under `/data/public` (matches `DocumentRoot` in `000-default.conf`).
+- PHP config changes belong in `php.ini` (image default) — downstream users override it by bind-mounting their own file over `/php/php.ini`, so avoid assuming values in `php.ini` are final.
+- Because `opcache.validate_timestamps=0`, PHP file changes require a container restart/FPM reload to take effect — relevant when iterating on `test/public` during image testing.
+- Sessions and app-level caching are expected to go through the `redis` service (session handler already wired to `tcp://redis:6379`); MariaDB is the expected DB backend (see `docker-compose.yml` env vars).

Dockerfile

@@ -1,39 +1,37 @@
-FROM debian:trixie-20260316
+FROM php:8.5.8-fpm-trixie
+
+ARG PHP_REDIS_VERSION=6.3.0
 
 WORKDIR /data
 
-# Install base packages + Apache + PHP repo
+# Install Apache + build deps for the PHP extensions we need
-RUN apt-get update && apt-get install -y \
+RUN apt-get update \
-    lsb-release \
+    && apt-get install -y --no-install-recommends \
         ca-certificates \
-    curl \
         logrotate \
         ssl-cert \
         apache2 \
+        libzip-dev \
+        libonig-dev \
+        pkg-config \
+        $PHPIZE_DEPS \
     && echo "ServerName localhost" >> /etc/apache2/apache2.conf \
     \
-    # Add Sury PHP repo
+    # PHP extensions (mysqli/pdo_mysql, mbstring, zip, redis)
-    && curl -sSLo /tmp/debsuryorg-archive-keyring.deb https://packages.sury.org/debsuryorg-archive-keyring.deb \
+    # xml + curl are already built into the base image
-    && dpkg -i /tmp/debsuryorg-archive-keyring.deb \
+    && docker-php-ext-install mysqli pdo_mysql mbstring zip \
-    && echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list \
+    && pecl install redis-${PHP_REDIS_VERSION} \
+    && docker-php-ext-enable redis \
     \
-    && apt-get update \
+    # Keep the runtime shared libs the compiled extensions link against;
+    # only the -dev/headers packages and build toolchain get dropped below
+    && apt-mark manual libzip5 libonig5 \
     \
-    # Install PHP 8.5 + extensions
+    # Drop the build-only toolchain and headers now that the extensions are built
-    && apt-get install -y \
+    && apt-get purge -y --auto-remove \
-        php8.5 \
+        $PHPIZE_DEPS \
-        php8.5-cli \
+        libzip-dev \
-        php8.5-fpm \
+        libonig-dev \
-        php8.5-mysql \
-        php8.5-xml \
-        php8.5-mbstring \
-        php8.5-curl \
-        php8.5-zip \
-        php8.5-redis \
-    \
-    # Cleanup
-    && apt-get autoremove -y \
-    && apt-get clean \
     && rm -rf /var/lib/apt/lists/* /tmp/*
 
 # Apache + PHP-FPM configuration + performance tuning
@@ -45,9 +43,6 @@ RUN \
     && a2dismod mpm_prefork \
     && a2enmod mpm_event \
     \
-    # Enable PHP-FPM
-    && a2enconf php8.5-fpm \
-    \
     # Remote IP config
     && echo 'RemoteIPHeader X-Forwarded-For' > /etc/apache2/conf-available/remoteip.conf \
     && echo 'RemoteIPTrustedProxy 127.0.0.1' >> /etc/apache2/conf-available/remoteip.conf \
@@ -64,57 +59,63 @@ RUN \
     && a2enconf compression \
     \
     # KeepAlive tuning
-    && cat <<EOF > /etc/apache2/conf-available/keepalive.conf
+    && printf '%s\n' \
-KeepAlive On
+        'KeepAlive On' \
-MaxKeepAliveRequests 100
+        'MaxKeepAliveRequests 100' \
-KeepAliveTimeout 2
+        'KeepAliveTimeout 2' \
-EOF \
+        > /etc/apache2/conf-available/keepalive.conf \
     && a2enconf keepalive \
     \
     # MPM Event tuning
-    && cat <<EOF > /etc/apache2/conf-available/mpm-event-tuning.conf
+    && printf '%s\n' \
-<IfModule mpm_event_module>
+        '<IfModule mpm_event_module>' \
-    StartServers             2
+        '    StartServers             2' \
-    MinSpareThreads         25
+        '    MinSpareThreads         25' \
-    MaxSpareThreads         75
+        '    MaxSpareThreads         75' \
-    ThreadLimit             64
+        '    ThreadLimit             64' \
-    ThreadsPerChild         25
+        '    ThreadsPerChild         25' \
-    MaxRequestWorkers      150
+        '    MaxRequestWorkers      150' \
-    MaxConnectionsPerChild 1000
+        '    MaxConnectionsPerChild 1000' \
-</IfModule>
+        '</IfModule>' \
-EOF \
+        > /etc/apache2/conf-available/mpm-event-tuning.conf \
     && a2enconf mpm-event-tuning \
     \
     # Logrotate
-    && cat <<EOF > /etc/logrotate.d/apache2
+    && printf '%s\n' \
-/var/log/apache2/*.log {
+        '/var/log/apache2/*.log {' \
-    weekly
+        '    weekly' \
-    missingok
+        '    missingok' \
-    rotate 4
+        '    rotate 4' \
-    compress
+        '    compress' \
-    delaycompress
+        '    delaycompress' \
-    notifempty
+        '    notifempty' \
-    create 640 root adm
+        '    create 640 root adm' \
-}
+        '}' \
-EOF
+        > /etc/logrotate.d/apache2 \
+    \
+    # PHP-FPM tuning (unix socket, to match the Apache vhost's proxy_fcgi handler)
+    && mkdir -p /run/php \
+    && sed -i \
+        -e 's|^;*listen = .*|listen = /run/php/php-fpm.sock|' \
+        -e 's/^;*listen.owner = .*/listen.owner = www-data/' \
+        -e 's/^;*listen.group = .*/listen.group = www-data/' \
+        -e 's/^;*listen.mode = .*/listen.mode = 0660/' \
+        -e 's/^pm = .*/pm = dynamic/' \
+        -e 's/^pm.max_children = .*/pm.max_children = 20/' \
+        -e 's/^pm.start_servers = .*/pm.start_servers = 2/' \
+        -e 's/^pm.min_spare_servers = .*/pm.min_spare_servers = 2/' \
+        -e 's/^pm.max_spare_servers = .*/pm.max_spare_servers = 5/' \
+        /usr/local/etc/php-fpm.d/www.conf
 
-# PHP-FPM tuning
+# PHP custom config — /php is layered in front of the image's default conf.d
-RUN sed -i 's/^pm = .*/pm = dynamic/' /etc/php/8.5/fpm/pool.d/www.conf && \
+ENV PHP_INI_SCAN_DIR="/php:${PHP_INI_DIR}/conf.d"
-    sed -i 's/^pm.max_children = .*/pm.max_children = 20/' /etc/php/8.5/fpm/pool.d/www.conf && \
-    sed -i 's/^pm.start_servers = .*/pm.start_servers = 2/' /etc/php/8.5/fpm/pool.d/www.conf && \
-    sed -i 's/^pm.min_spare_servers = .*/pm.min_spare_servers = 2/' /etc/php/8.5/fpm/pool.d/www.conf && \
-    sed -i 's/^pm.max_spare_servers = .*/pm.max_spare_servers = 5/' /etc/php/8.5/fpm/pool.d/www.conf
-
-# PHP custom config
-RUN mkdir -p /php && echo "PHP_INI_SCAN_DIR=/php" > /etc/environment
 
 COPY php.ini /php/php.ini
 COPY 000-default.conf /etc/apache2/sites-available/000-default.conf
+COPY --chmod=755 start.sh /start.sh
+
+RUN a2ensite 000-default
 
 EXPOSE 80
 
-# Startup
-COPY start.sh /start.sh
-RUN chmod +x /start.sh
-
 CMD ["/start.sh"]

README.md

@@ -9,7 +9,8 @@ It provides a streamlined stack featuring Apache, the latest PHP version, Redis,
 
 ## Features
 
-- **PHP Version**: 8.5.3
+- **Base**: official `php:8.5.8-fpm-trixie` image (Debian Trixie)
+- **PHP Version**: 8.5.8 (pinned)
 - **Apache Web Server**: Configured to run PHP applications
 - **Support for**:
   - `remoteip` (reverse proxy)
@@ -33,9 +34,9 @@ cd corxn
 
 ```bash
 sudo su
-docker buildx build --no-cache -t 4lights/corxn:8.5.3 -t 4lights/corxn:latest --load .
+docker buildx build --no-cache -t 4lights/corxn:8.5.8 -t 4lights/corxn:latest --load .
 docker login -u <username>
-docker push 4lights/corxn:8.5.3
+docker push 4lights/corxn:8.5.8
 docker push 4lights/corxn:latest
 ```
 # Testing

docker-compose.yml

@@ -1,7 +1,7 @@
 # Sample Docker Compose
 services:
   corxn:
-    image: 4lights/corxn:latest
+    image: 4lights/corxn:8.5.8
     ports:
       - "8000:80"
     volumes:

start.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 set -e
 
-service php8.5-fpm start
+php-fpm -D
 
 exec apachectl -D FOREGROUND