Deployment and operations

Adocommerce Kit runs inside the host AdonisJS application. The host therefore owns deployment order, database migrations, HTTP scaling, queue workers, logs, metrics, and backups.

Production baseline

Before the first production deployment:

use Node.js 24 or newer and a supported Lucid database;
pin the same exact beta version of every @adocommercekit/* package;
commit config/commerce.ts, published migrations, storefront files, and .commercekit/publications;
replace the manual payment method unless offline payment is intentional;
configure a shared queue dispatcher for multiple application instances;
replace the generated in-process rate limiter for multiple instances;
configure HTTPS, trusted proxy behavior, database backups, and secret storage;
exercise checkout, payment, webhook, and refund behavior in the target environment.

Deployment sequence

A conservative deployment runs in this order:

Build and test the exact commit and lockfile that will deploy.
Back up the database according to the database provider’s recovery procedure.
Run node ace migration:run once from a release task.
Start or roll out the new application and queue workers.
Run node ace commerce:doctor against the deployed configuration and database.
Exercise a catalog read and a non-destructive cart request.
Verify maintenance jobs and payment webhooks are being processed.

Do not run the package configurators on every application boot. Run them during development, review their output, and deploy the generated files with the application.

Health checks

Structural check

node ace commerce:doctor

Use the doctor command after install, after configuration changes, after package upgrades, and as a release verification task. Application boot validates configuration and the model registry; the command then checks required tables, payment driver capabilities, and inventory reservation totals.

A doctor failure should fail the release. It is a diagnostic command, not an HTTP liveness endpoint; add a small host-owned endpoint for your platform if one is required.

Runtime smoke

With the optional storefront API installed:

curl --fail-with-body https://your-store.example/api/commerce/products?perPage=1
curl --fail-with-body -c /tmp/commerce-cookie \
  https://your-store.example/api/commerce/cart

The second request may create an anonymous cart. Use an isolated environment or remove the cart afterward if synthetic data is undesirable.

Commerce CLI

Adocommerce Kit extends the host application’s Ace console. Run commands as node ace commerce:*; there is no separate global executable or second configuration context.

Setup and automation

commerce:setup inspects the installed @adocommercekit/* packages without booting the application. It checks published configuration or route sentinels, driver environment declarations, registrations in config/commerce.ts, commerce migrations, and publication baselines. It never modifies the host.

node ace commerce:setup
node ace commerce:setup --json
node ace commerce:doctor --json
node ace commerce:upgrade --check
node ace commerce:upgrade --json
node ace commerce:upgrade --yes

--json writes one command report for CI. Application and database debug logs remain controlled by the host’s logging configuration. Diagnostic commands use exit code 0 when clean, 1 when action is required, and 2 for invalid command usage or an unreadable host manifest.

commerce:upgrade --check and commerce:upgrade --json inspect without prompting or writing. --yes applies every offered publication and migration. Do not combine --check with --yes. A staged three-way publication conflict still exits with 1 in --check, --json, or --yes automation modes.

Maintenance

Run one scheduled maintenance implementation immediately:

node ace commerce:maintenance reservations
node ace commerce:maintenance carts
node ace commerce:maintenance checkouts
node ace commerce:maintenance outbox

The four tasks invoke the same ExpireStaleReservations, ExpireAbandonedCarts, ReconcileStuckCheckouts, and DrainEventOutbox classes used by the scheduler. They are not dry runs. Add --json for a machine-readable affected count or outbox delivery result. An outbox result with failed deliveries exits with 1; an unknown task exits with 2.

Host-owned driver extensions

Publish a functional host-owned extension of a stable driver:

node ace commerce:make:driver payment acme
node ace commerce:make:driver shipping warehouse-rate
node ace commerce:make:driver tax local-tax
node ace commerce:make:driver inventory nearest-warehouse

The command writes a service under app/services/commerce/drivers and prints the import and config/commerce.ts registration. Generated drivers delegate to the corresponding built-in behavior so they compile and run before customization. Payment extensions delegate to the manual payment provider and must be connected to the intended external provider before production use.

Scheduled jobs

Adocommerce Kit schedules these jobs when the service provider starts:

Job name	Default schedule	Purpose
`commerce.expire_stale_reservations`	Every 5 minutes	Release expired inventory reservations
`commerce.expire_abandoned_carts`	Hourly	Mark inactive carts abandoned and emit the event
`commerce.reconcile_stuck_checkouts`	Every 5 minutes	Recover checkouts older than the reservation threshold
`commerce.drain_event_outbox`	Every minute	Deliver pending transactional outbox events
`commerce.purge_expired_idempotency_keys`	Daily	Delete expired idempotency records

The default inline dispatcher creates timers inside the Adonis process. It is appropriate for development and a single long-lived process. It is a poor default for horizontal scaling, serverless instances, or frequently recycled processes because every process schedules its own copy and timers disappear when the process stops.

For a multi-instance deployment:

// config/commerce.ts
jobs: { dispatcher: 'queue' },

Install and configure the compatible @adonisjs/queue peer dependency and run its workers according to that package’s deployment model. The queue adapter is experimental while the upstream package remains pre-1.0, so cover it in release tests.

Monitor job age, failures, and duration. In particular, alert when stale reservations, stuck checkouts, or outbox rows continue growing beyond more than one schedule interval.

Transactional event outbox

Enable the outbox when event delivery must survive a process crash after the business transaction commits:

 events: {
   outbox: {
     enabled: true,
     drainBatchSize: 100,
   },
 },

The drain job runs every minute. Set a batch size your event handlers and database can process within that interval. Event handlers must remain idempotent because at-least-once delivery can repeat work after partial failures.

Keep the outbox disabled if no durable integration consumes it; enabling storage without monitoring the drain only creates an unbounded operational queue.

HTTP scaling and rate limits

The generated storefront applies fixed-window limits per client IP:

120 cart mutations per minute;
10 checkout attempts per minute;
60 order reads per minute.

The published limiter stores bounded counters in one Node.js process. In a multi-instance deployment, each instance has an independent limit. Replace app/middleware/commerce_rate_limit_middleware.ts with a shared Redis, database, or gateway-backed limiter while preserving the route policies.

Configure Adonis proxy trust correctly before relying on client IP. An attacker must not be able to choose the forwarded address used as the rate-limit key.

Payment webhooks

The generated endpoint is:

POST /api/commerce/webhooks/payments/:provider

Operational requirements:

preserve the raw request bytes through the proxy and Adonis middleware chain;
exclude only the webhook path from browser CSRF checks;
verify the provider signature before normalization;
keep provider secrets in the deployment secret store;
alert on signature failures and repeated handler errors;
retain enough request correlation metadata to trace a provider event to its payment intent and order.

Verified duplicate and unhandled events return 200 by design. A 200 therefore means the delivery was accepted, not necessarily that it changed a payment. Inspect stored webhook-event state when reconciling provider and application records.

See Stripe payments for provider-specific setup.

Database and backups

Adocommerce Kit stores financial amounts as integer minor units and copies cart state into order snapshots. Treat order, payment, refund, inventory, idempotency, webhook, and outbox tables as application records covered by the same backup and retention policy as the host user data.

At minimum:

run automated backups and test restoration;
use one release task for migrations rather than every web instance;
observe database lock waits during checkout and inventory contention;
retain completed order and payment records according to legal and accounting requirements;
anonymize customer PII through the domain service rather than deleting financial history ad hoc.

Changing tablePrefix after migration requires a deliberate host migration. The configuration change alone points Adocommerce Kit at new table names.

Logs, metrics, and alerts

Adocommerce Kit uses structured exceptions but does not install a monitoring backend. The host should record the commerce error code, request or job correlation ID, cart/order/payment identifiers, and provider event ID without logging card data, payment tokens, secrets, or full addresses.

Useful counters and alerts:

checkout success, conflict, price-change, stock, and payment-decline rates;
checkout latency and database lock time;
reservation expiration and stuck-checkout reconciliation counts;
webhook signature failures, duplicates, unhandled types, and processing failures;
outbox backlog age and drain failures;
payment authorization-to-capture and refund failures;
pending-payment expiry, under/overpayment, conflicting provider status, and paid-after-expiry review counts;
dynamic quote rejection and fulfillment return/restock failures;
commerce:doctor release failures.

Upgrade procedure

Generated files use a recorded publication baseline. Upgrade in a development branch, never directly on a production host. Official packages use lockstep versions, so raise every installed package in one command rather than a subset:

pnpm up --save-exact @adocommercekit/core@<version> \
  @adocommercekit/storefront-api@<version> \
  @adocommercekit/stripe@<version> \
  @adocommercekit/midtrans@<version> \
  @adocommercekit/xendit@<version> \
  @adocommercekit/id@<version> \
  @adocommercekit/biteship@<version> \
  @adocommercekit/rajaongkir@<version> \
  @adocommercekit/whatsapp@<version>
node ace commerce:upgrade

Drop the lines for packages the host does not install. Never mix official package versions in a production pilot.

Then:

Read package release notes and the stability policy.
Review new migration stubs and every generated-file diff.
Resolve files staged under .commercekit/incoming; the command does not overwrite host changes.
Keep .commercekit/publications updated and committed.
Run application typecheck, tests, and a complete checkout smoke.
Back up the database and use the normal deployment sequence.

commerce:upgrade --yes accepts safe add/update actions non-interactively, but it still does not resolve conflicts. Do not use it as a substitute for reviewing host-owned code.

Upgrade to 1.1.0

Migration 010_generic_seams is additive on populated SQLite, PostgreSQL, and MySQL databases. It adds nullable/defaulted parcel, quote, deferred-payment, webhook-status, fulfillment, and metadata columns plus the payment_instructions table. Run it before enabling a deferred, COD, quote, or fulfillment provider.

commerce:upgrade also proposes the 14th storefront route, the payment-instruction controller action, checkout quote-token validation, and transformer hydration. The instruction route must keep the same guest-token/authenticated-customer ownership check as the order route.

An upgraded host with its existing payment methods and static shipping configuration remains on the authorize/capture path. Enabling a deferred provider in production additionally requires jobs.dispatcher: 'queue'; verify this with node ace commerce:doctor.

Rollback the application before enabling a new seam. The previous application ignores migration 010’s additive fields and table, so the schema may remain in place for a forward fix. Do not run migration down() in production after instructions, quote selections, or fulfillment data have been written; doing so discards those records and columns.

Upgrade regional packages

The Indonesia packages build on the generic deferred-payment, shipping, fulfillment, and jobs seams without changing an unmodified host’s behavior. Each regional package publishes its own migrations or host-owned integration files. @adocommercekit/id adds the kode-unik lease table and the Indonesian regional, PDP, and COD tables, plus config, validator, controller, and route stubs tracked through @adocommercekit/id/upgrade.

Before enabling any regional provider in production:

configure a durable queue and set jobs.dispatcher: 'queue'; deferred payments, COD, and WhatsApp retries all depend on it;
import a licensed region source with commerce:id:regions-import, because no region rows are bundled;
pin each provider’s API version and revalidate it against the live provider contract;
confirm webhook verification is configured; Biteship tracking and WhatsApp fail closed without a host verifier;
run node ace commerce:doctor so driver credential pings and the deferred-payment queue requirement are checked.

Use Build commerce for Indonesia for the complete capability map and the PDP operations runbook for consent, rights, retention, and incident duties.

Rollback

Application rollback is safe only when the previous application version can read the migrated schema. Before applying a migration, determine whether it is backward compatible with the currently running version.

If it is not:

stop the rollout before mixed versions serve traffic;
take a verified backup;
deploy application and schema in an explicitly coordinated window;
restore from backup or apply a reviewed forward fix if rollback is required.

Do not edit or delete already-applied Adocommerce Kit migration files to force a rollback. Add host migrations that express the intended change and preserve the migration history.