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