ProcessWire development and production in the AI era: how not to overwrite a live site

[maximus]

Once a ProcessWire site is live, the production database is not a deployable artifact. It is the source of truth for content, users, roles, module settings, and module-owned data.

Deploy code from Git. Apply reviewed migrations to the production database. Preserve production data, uploads, configuration, and secrets. If an AI coding agent is involved, write these boundaries down in AGENTS.md and enforce them with scripts rather than relying on the agent to infer what “deploy” means.

I arrived at this rule through a real incident.

The incident

I was rebuilding a ProcessWire site locally with an AI coding agent. The data model had changed substantially, the development site contained useful demo content, and the production site had little activity. I asked the agent to deploy the new version and replace the old data.

Technically, the operation succeeded:

• the code was deployed;
• the new schema appeared;
• the development database was imported;
• development uploads replaced production uploads;
• the public pages worked.

But a database is not just “content”. The import also replaced production-only module configuration, users, roles, support tickets, AI conversations, and records stored in custom module tables. SMTP happened to survive because its configuration matched in both environments. Other settings did not.

Backups existed, so the incident was recoverable. The site also had almost no real activity. On a busy site, the same operation could have destroyed orders, form submissions, member accounts, unpublished editorial work, audit history, or messages created during the deployment window.

The important lesson was not “the AI made a mistake”. The deployment process allowed an ambiguous instruction to become a destructive database operation. That is a systems problem.

Why ProcessWire needs an explicit deployment model

ProcessWire's file layout is deliberately clear: /wire/ contains the core, while /site/ contains site-specific templates, modules, configuration, and assets. The official documentation also identifies site/config.php as the site configuration file and site/assets/ as writable runtime storage.

That filesystem separation is useful, but a mature ProcessWire project has another boundary that is easier to miss:

Deployment ownership map

• Git release — templates, hooks, module code, and frontend assets. Source of truth: the repository.
• Database structure — fields, templates, fieldgroups, and module schemas. Source of truth: reviewed migrations.
• Production database — pages, users, roles, settings, submissions, and module-owned tables. Source of truth: production.
• Runtime configuration — database credentials, hostnames, and environment flags. Source of truth: the production runtime.
• Secrets — SMTP, API, and OIDC credentials. Source of truth: a secret store or protected runtime files.
• Writable assets — uploads, generated files, logs, sessions, and backups. Source of truth: production storage.

The initial launch is special. If production is empty, cloning a reviewed development database may be reasonable. After the first real user, form submission, editor change, or module configuration, that direction must stop.

Production may flow to development through a protected and preferably sanitized snapshot. Development must not flow back as a whole database.

This is the same problem described in ProcessWire's own article introducing migrations: once the live server receives content while features continue to be developed locally, the databases diverge and changes must be merged rather than replaced.

Use releases for code and migrations for change

A production release should be an immutable Git commit, preferably accompanied by a tag. Build the deployable file list from that commit—not from the current working directory.

A release manifest should include only public runtime code and static assets. It should explicitly exclude:

• .git/ and CI configuration;
• AGENTS.md and development documentation;
• site/config.php and environment-specific config;
• database dumps, credentials, and private keys;
• site/assets/files, caches, logs, sessions, and backups;
• tests, fixtures, local tooling, and editor configuration.

ProcessWire fields and templates live in the database, so code deployment alone is not always sufficient. Represent structural changes as idempotent, versioned migrations. A migration may use ProcessWire's API, a migration module, or a project-specific CLI script. The important properties are the same:

1. it has a preview or audit mode;
2. it is safe to run more than once;
3. it changes only named structures or records;
4. it preserves unknown production configuration;
5. large transformations are bounded and resumable;
6. destructive steps require a fresh verified backup and rollback data;
7. successful application is recorded.

ProcessWire has community options such as ProcessDbMigrate and migration modules, but no tool removes the need to classify production data correctly.

A backup is not verified until it can be restored

“The backup command returned zero” is not enough.

For every production release:

1. create a timestamped database backup outside the document root;
2. verify its size and checksum;
3. verify compressed-stream integrity;
4. periodically restore it into an isolated database;
5. keep a backup of the exact files being replaced;
6. record the rollback path before changing production.

This matters because backup tools can produce syntactically valid-looking files that fail only during restoration. Test the recovery path, not merely the backup button.

The official ProcessWire upgrade guide likewise recommends backing up both files and database and testing upgrades on a development or staging site first.

Add a fail-closed deployment guard

Documentation is necessary, but an executable invariant is better.

Before deployment, create a private snapshot containing no secret values:

• row counts for protected tables;
• page counts by template;
• stable page IDs by template;
• installed module names;
• names and configured/empty state of module configuration keys;
• intended Git commit;
• production hostname;
• verified backup metadata.

After code deployment and migrations, take the same measurements and compare them. Block completion if:

• a protected table disappeared or lost rows;
• a pre-existing page ID disappeared;
• a template or installed module disappeared;
• a module configuration key disappeared;
• a configured value became empty;
• the host or release commit does not match.

Stable IDs matter. Row counts alone can miss a replacement database containing the same number of different records.

Some legitimate migrations intentionally remove obsolete data. That should be an exceptional workflow requiring a change ID, a table-by-table impact report, a tested restore, and a second explicit approval. A generic “deploy everything” instruction must never authorize it.

What to tell an AI coding agent

An AI agent is fast enough to turn an ambiguous sentence into a complete deployment before a human notices the ambiguity. Give it a narrower contract.

The repository instructions should state:

• development and production paths and hostnames;
• production is read-only unless a production change is explicitly requested;
• commit, push, deploy, migrate, publish, and replace data are separate actions;
• “deploy” means code-only unless named migrations are included;
• a development database must never overwrite a launched production database;
• production users, content, module configuration, custom tables, and uploads must be preserved;
• secrets must not be read, printed, hashed, copied locally, or committed;
• every mutation needs a fresh verified backup and exact rollback path;
• migrations run in preview first and must be bounded/idempotent;
• a data decrease is a blocker, not a warning;
• if scope is ambiguous, stop after read-only investigation;
• destructive approval is two-phase: impact report first, explicit confirmation of that report second;
• maintenance is not removed and success is not reported while checks fail.

The open AGENTS.md format is useful here because it gives multiple coding agents a predictable repository-level instruction file. Its documentation explicitly recommends including build commands, testing, security concerns, and deployment details, and supports more specific nested files where needed.

I prepared a reusable template and attached it to this post as ProcessWire-AGENTS-production-safety-template.zip. The archive contains a single AGENTS.md file. Download it, replace the placeholders, and commit it to the root of your project. Do not deploy it into the public document root.

A practical release checklist

Before maintenance

• Select an immutable Git commit.
• Review the diff and release manifest.
• List every migration and classify its risk.
• Create and verify database and file backups.
• Create the protected data snapshot.
• Write the rollback command/path.

During maintenance

• Deploy only manifest files.
• Preserve production config, secrets, uploads, logs, sessions, and backups.
• Run migrations in preview, then apply.
• Run the fail-closed comparison.
• Stop on any unexplained decrease.

Before reopening

• Test origin and CDN routes.
• Test authentication and representative member workflows.
• Verify email delivery readiness and background jobs.
• Inspect new logs without exposing secrets.
• Record commit, manifest checksum, migration results, backups, and rollback.
• Remove maintenance only when every blocker is resolved.

Final principle

The database is not “the backend version of the code”. On a live ProcessWire site it is accumulated production state.

AI does not change this rule. AI makes it more important to encode the rule in files, scripts, permissions, and fail-closed checks—because the agent can execute a bad assumption much faster than a human can recognize it.

References

• ProcessWire file and directory structure
• ProcessWire: migrating to production
• ProcessWire upgrade best practices
• ProcessWire file permissions and protecting site/config.php
• ProcessWire: Introduction to the Migrations module
• ProcessDbMigrate module directory entry
• AGENTS.md open format

ProcessWire-AGENTS-production-safety-template.zip

 

 

 

 

[Ivan Gretsky]

Thanks for this useful post 🙏!  I think this kind of tutorials are very important.

1. To make it even more practical, could you somehow share a step by step workflow?  Not what to do, but exactly how you think it should be done.  What tools, what commands, where to look for what. Maybe I'm asking for too much. It's better to ask than not)
2. What migration strategy, module, tool do you use? Could you elaborate on this a bit?

[Peter Knight]

Great insights there. Your issues have revealed a few gaps in my own AI modules workflow. 

I tend not to replace databases wholesale (anymore), but this is a relatively new approach for me, and I am still tweaking it.
I.E. the production database is regarded as something I push specific changes to, not something I replace wholesale.
It makes syncing the changes more granular, preview-first, and path-aware. Which I kinda prefer as it feels more surgical.

But I have the benefit of working on medium-ish sites with no external contributors, which certainly helps.

BTW, on the subject of the gaps you highlighted, I'll feed them into my own AI module (with your permission) and that's how I evolve it.
Anytime I have an issue, it gets fed back into the model, and over time, has evolved into a really great part of my workflow.

[maximus]

@Ivan Gretsky Thank you — you are not asking for too much. The commands are the useful part, and this probably deserves a follow-up post with a small reference repository.

My current workflow is deliberately boring and project-specific:

1. Select the release from Git, never from the working tree:

git status --short
git rev-parse HEAD
git diff --check
git tag -a vX.Y.Z -m "Release vX.Y.Z"

2. Build an allowlist from that exact commit. In my project this is:

php site/templates/scripts/build-release-manifest.php --commit="$(git rev-parse HEAD)" --output=/private/releases/vX.Y.Z/manifest.txt
sha256sum /private/releases/vX.Y.Z/manifest.txt

3. Run a read-only production preflight: verify the host and document root, PHP/database versions, free disk space, maintenance mechanism, and classify every migration as additive, transforming, or destructive.

4. Create a database backup outside the web root, verify its size, checksum and compression, and periodically prove it with an isolated restore. I also back up only the production files listed for replacement.

5. Create a protected pre-deploy snapshot. My guard records table counts, page IDs grouped by template, installed modules, module configuration key presence (never secret values), host, commit and backup metadata:

php site/templates/scripts/deployment-guard.php --environment=production --snapshot=/private/deployments/DEPLOY_ID/pre.json --backup=/private/backups/DEPLOY_ID/production-before.sql.gz --commit=FULL_COMMIT

6. Deploy only the committed allowlist. tar, rsync or scp are all fine when driven by the reviewed manifest; a full workspace sync and a development database import are not.

7. Run each migration in preview mode, review it, then apply it:

php site/templates/migrations/2026-08-11-example.php
php site/templates/migrations/2026-08-11-example.php --apply

8. Run the guard in compare mode and fail closed:

php site/templates/scripts/deployment-guard.php --environment=production --compare=/private/deployments/DEPLOY_ID/pre.json --commit=FULL_COMMIT

9. Smoke-test origin and CDN, login/member flows, forms/email readiness/background jobs, and inspect new logs before leaving maintenance mode.

For migrations, I do not use one universal module for everything. On this project I use small, versioned CLI PHP migrations built on the ProcessWire API. Fields, templates, fieldgroups and named structural module settings are changed through ProcessWire, not by replacing the database. Module-owned table migrations live with the module. Every script has preview/apply modes, is idempotent, and large jobs are bounded and resumable. Direct SQL is reserved for a reviewed migration of a table the module owns.

ProcessDbMigrate or another migrations module can absolutely implement the same policy. For me the important part is not the brand of tool but the contract: preview first, named changes only, preserve unknown production state, record what ran, and stop on unexplained decreases.

The ZIP attached to the original post contains the AGENTS.md safety template, not these project scripts. I can publish generic versions of the manifest builder, deployment guard and an example migration in a follow-up, with placeholders and without LQRS-specific assumptions.

@Peter Knight Yes, absolutely — please use, adapt and feed any of these gaps into your AI module. That feedback loop is exactly what I am trying to formalise: every incident should become a persistent rule, a check, or an executable invariant instead of remaining a memory. I would also be interested to see how your more surgical, path-aware workflow evolves.