CORXN/AGENTS.md

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. 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:

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:

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)

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).