Skip to content

AGENTS.md

Latest commit

 

History

History
117 lines (89 loc) · 4.79 KB

AGENTS.md

File metadata and controls

117 lines (89 loc) · 4.79 KB
Raw

AGENTS.md

Project

Docker Compose deployment for WordPress + MariaDB 11 + Redis 7. Two web server variants: Nginx+PHP-FPM (default, recommended) and Apache. Not a theme/plugin project — the repo defines container images and orchestration.

Compose variants

File Web server Use case
compose.yaml Nginx + PHP-FPM (supervisor) Default, Coolify-ready
compose.apache.yaml Apache mod_php Legacy / simpler
compose.dev.yaml Overlay only Adds phpMyAdmin, exposes MariaDB port

Each compose file is self-contained and Coolify-compatible (uses expose not ports, env vars only, no Docker secrets).

Key files

  • Dockerfile — Nginx+PHP-FPM image on php:8.3-fpm-bookworm; adds WP-CLI, redis/igbinary/imagick extensions, nginx+supervisor configs
  • Dockerfile.apache — Apache image on wordpress:php8.3-apache; adds WP-CLI, redis/igbinary extensions, Apache mods, security headers
  • config/ — Nginx, PHP-FPM, supervisor, and PHP ini configs for the Nginx variant
  • docker-entrypoint.sh — Nginx variant: waits for MariaDB/Redis, downloads WordPress, creates wp-config.php, handles migrations, HTTPS detection, permissions
  • docker-entrypoint-apache.sh — Apache variant: cache cleanup, optional Redis flush, Matomo dirs/permissions, uploads .htaccess, session purge
  • .env.example — Template for required env vars

Setup

  1. Copy .env.example to .env and fill in passwords
  2. docker compose up -d (nginx) or docker compose -f compose.apache.yaml up -d (apache)
  3. First start: WordPress is auto-downloaded; visit /wp-admin/install.php to complete GUI install

Operational notes

  • WP Cron disabled by default (DISABLE_WP_CRON env var); external scheduler must hit wp-cron.php
  • FLUSH_REDIS_ON_STARTUP env var (default false) — set true to flush Redis on container start
  • Redis uses igbinary serialization (WP_REDIS_IGBINARY enabled); requires igbinary + redis PHP extensions
  • Nginx variant: uploads PHP execution blocked via nginx location block; rate limiting on wp-login.php; xmlrpc.php denied
  • Apache variant: uploads PHP execution blocked via .htaccess (secure-uploads.sh)
  • Both variants: Cloudflare trusted proxy ranges configured; X-Forwarded-Proto / CF-Visitor set HTTPS=on
  • Nginx entrypoint auto-detects migration from Apache variant and handles credential/Redis config update
  • All services run with cap_drop: ALL + minimal cap_add

No build/test/lint pipeline

Infra repo — no package manager, no tests, no CI. Verify changes with:

  • docker compose build — rebuild the image
  • docker compose up -d && docker compose logs -f — runtime validation
  • docker compose exec wordpress wp <command> — WP-CLI inside the container

Commit conventions

All commits MUST follow Conventional Commits.

Format

type(scope): short description

optional body

Types

Type When to use
feat New feature or capability
fix Bug fix
docs Documentation changes only
style Formatting, whitespace, no code change
refactor Code restructuring, no behavior change
perf Performance improvement
test Adding or fixing tests
chore Maintenance, deps, tooling, CI
ci CI/CD pipeline changes
revert Reverting a previous commit

Scopes

Scope What it covers
nginx Nginx variant: compose.yaml, Dockerfile, docker-entrypoint.sh, config/
apache Apache variant: compose.apache.yaml, Dockerfile.apache, docker-entrypoint-apache.sh
dev Dev overlay: compose.dev.yaml
redis Redis configuration or entrypoint cache logic
mariadb MariaDB configuration
docs README, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT
ci GitHub workflows, templates
repo Root-level files: .gitignore, .env.example, AGENTS.md, LICENSE

Rules

  1. One type per commit — do not mix feat and fix in the same commit
  2. Lowercase type and scope — feat(nginx): not Feat(NGINX):
  3. Imperative mood — "add rate limiting" not "added rate limiting"
  4. No period at end of subject line
  5. Max 72 chars for subject line
  6. Body is optional but required for breaking changes
  7. Breaking changes: append ! to type (feat(nginx)!: ...) and document in body with BREAKING CHANGE: prefix

Examples

feat(nginx): add rate limiting on wp-login.php
fix(apache): resolve Redis flush on startup
docs: add CONTRIBUTING.md and SECURITY.md
chore(repo): update .gitignore patterns
refactor(nginx): simplify entrypoint health check logic
perf(mariadb): tune InnoDB buffer pool to 512MB

Never commit

  • Secrets, passwords, API keys, .env files
  • Generated files or build artifacts
  • Unrelated changes bundled together