Skip to content

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.

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;
  • bind a shared rate-limit store for multiple instances instead of the default in-process store;
  • 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:

  1. Build and test the exact commit and lockfile that will deploy.
  2. Back up the database according to the database provider’s recovery procedure.
  3. Run node ace migration:run once from a release task.
  4. Start or roll out the new application and queue workers.
  5. Run node ace commerce:doctor against the deployed configuration and database.
  6. Exercise a catalog read and a non-destructive cart request.
  7. 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.

Doctor also warns about existing outbound destinations when the outbox is disabled, and old Stripe drivers that assume exponent 2 for currencies with a different core exponent and lack scaling support. Enable durable delivery or deactivate destinations as appropriate; upgrade Stripe rather than altering recorded money to hide a warning.

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 registration instructions. It supports payment, shipping, tax, inventory, fulfillment, shipping-quote, cart-token, pricing, search, image-storage, shipping-eligibility, tax-address, order-number, and job-dispatcher. The first four delegate to built-in behavior; payment uses the manual provider until you wire the intended gateway. Additional typed factories require an explicit working delegate. Register job-dispatcher adapters in a host provider’s boot hook after commerce, through JobDispatcherService.use(). See all ports and registration details.

Scheduled jobs

Adocommerce Kit schedules these jobs when the service provider starts:

Job name Default schedule Purpose
commerce.expire_pending_payments Every minute Revalidate deferred payments and expire unpaid intents
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.reconcile_payment_operations Every 5 minutes Reconcile durable external payment operation claims
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.

The maintenance CLI exposes only reservations, carts, checkouts, and outbox. Payment expiry, payment-operation reconciliation, and idempotency cleanup run through their registered jobs; do not invent commerce:maintenance task names for them. Pending capture/refund rows and started/uncertain payment operations must be reconciled against provider state before another attempt. Use the authorized admin payment-operations reconciliation workflow when automatic reconciliation cannot establish the result.

With promotions installed, its provider also schedules commerce:promotions:expire-pending every five minutes to release expired pending redemptions. Keep this job running even when no storefront promotion management UI is used.

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.

Inspect failed outbox records with EventOutboxService.deadLetters({ cursor, limit }); it returns { items, nextCursor }. Pass the opaque next cursor back unchanged: ordering is UUID ID descending, not creation-time ordering. replay(id, options) resets a failed row to pending and returns whether a row was reset; optional trx participates in a host transaction.

Outbound destination administration

Enable the outbox before creating or activating a destination. Secrets and custom headers are encrypted; await toAdminDestination() for the masked destination DTO and use toAdminDelivery() for the minimal delivery DTO. Neither is a raw payload/credential export. Omitted update headers preserve values, null clears them, and an object replaces them. rotateSecret() returns { secret } once: store it securely, because subsequent reads are masked. ping() sends a real test delivery and refuses inactive destinations; replayDelivery() refuses inactive destinations and only accepts failed/dead-lettered deliveries.

listDeliveries({ destinationId, status, cursor, limit }) returns { items, nextCursor } using opaque UUID-descending pagination. Destination mutations, secret rotation, ping, and delivery replay accept mutation transaction options. Review outbound network, timeout, and header safeguards before exposing management actions.

HTTP scaling and rate limits

The generated storefront applies fixed-window limits:

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

Cart mutation and checkout scopes use the configured cart credential when present, falling back to client IP; order-read scopes use client IP. The default MemoryRateLimitStore stores bounded counters in one process. For multiple instances, bind a RateLimitStore under the exported STOREFRONT_RATE_LIMIT_STORE container key. The published middleware uses that binding without replacement. RedisRateLimitStore is supplied for Redis clients with the standard eval(script, numberOfKeys, ...args) signature; hosts may provide another atomic shared store implementing consume().

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.

CustomerService.anonymize(customerId) clears customer/address PII, cart addresses, linked order emails/address snapshots and metadata, saved payment identities, and stored provider payloads while preserving financial rows. Order address redaction retains country codes for tax reporting. Migration 019_customer_privacy adds the anonymizedAt marker. This is not an automatic core retention schedule: retention windows and legal holds belong to the host or the optional Indonesia PDP integration.

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/promotions@<version> \
  @adocommercekit/preorders@<version> \
  @adocommercekit/store-credit@<version> \
  @adocommercekit/engagement@<version> \
  @adocommercekit/storefront-api@<version> \
  @adocommercekit/admin-api@<version> \
  @adocommercekit/admin@<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:

  1. Read package release notes and the stability policy.
  2. Review new migration stubs and every generated-file diff.
  3. Resolve files staged under .commercekit/incoming; the command does not overwrite host changes.
  4. Keep .commercekit/publications updated and committed.
  5. Run application typecheck, tests, and a complete checkout smoke.
  6. 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.

The report distinguishes noop (stock-equivalent, baseline healed during apply), kept (retain host customization), removed-by-host (preserve deletion), unconfigured (no recorded publication ownership), and error as well as add/update/conflict. New publications are discovered only within a package already represented by a baseline; installation alone does not authorize publishing files. Hash comparison only normalizes leading BOM, CRLF, and trailing newlines. Resolve loader/read errors before deployment. Advisory IDs and summaries accompany affected artifacts. A security advisory fails automated check status while its fix is unapplied: an unmerged conflict, or a pending update under --check. A kept copy has already been merged against the current stock source, so its advisory is reported but does not fail the check.

Optional upgrade loaders include storefront API, admin API/panel, Indonesia, promotions, preorders, store credit, engagement, WhatsApp, and Biteship. After manual merging, the publication base must contain incoming stock source, never the resolved customized host output. Keep host customizations outside that baseline.

Panel extensions (Indonesia, promotions) are offered by commerce:upgrade only after the extension was configured against a published panel, because the extension’s panel controllers render its pages. If you install @adocommercekit/admin after such a package, re-run node ace configure @adocommercekit/<package> once to publish its pages, controllers, and registration together.

Current core and domain migrations

The ordered exported coreMigrations registry now includes 015_returns, 016_operational_depth, 017_payment_reconciliation, 018_inventory_backorders, 019_customer_privacy, and 020_webhook_hardening. Review each missing migration offered by upgrade and run node ace migration:run after publication. Migration 017 backfills legacy captures/refund associations and preserves the backfilled money ledger on rollback. Migration 020 encrypts existing destination headers and removes plaintext storage; migrate custom destination models to nonserialized headersEnc and retain encryption keys.

The complete ordered stub chain is:

Range Migrations
001–005 foundation, catalog, customers, pricing, fulfillment_taxes
006–010 carts, orders_inventory, payments_infrastructure, transaction_beta, generic_seams
011–015 admin_seams, product_images, durability_hardening, external_events, returns
016–020 operational_depth, payment_reconciliation, inventory_backorders, customer_privacy, webhook_hardening

Migration 018 adds reservations.backordered_quantity and its FIFO lookup index; consumption preserves nonnegative on-hand stock and later receipts satisfy outstanding backorders. Migration 019 adds customers.anonymized_at; deploy it before invoking the updated anonymization service.

Promotions’ ./upgrade loader tracks validators, storefront and management controllers/routes, the existing-schema promotion_kinds migration, and conditional panel pages/navigation/catalog files. Admin API publications require its host service to have been published; panel publications require the panel host. Review the offered artifacts, configure the intended surfaces when not yet owned, and migrate before using new campaign kinds.

Existing preorder hosts receive the additive preorder_deposits migration through commerce:upgrade or node ace configure @adocommercekit/preorders, followed by node ace migration:run. Fresh preorder schema already includes deposit fields. Legacy allocations remain fully paid with zero outstanding balance.

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.

Contributor and release gates

The release train is derived from nonprivate package manifests, including create-adocommerce, @adocommercekit/store-credit, and @adocommercekit/engagement, rather than a fixed package list. Tagged releases first run scripts/check_release_tag.mjs: v<version> must match every train manifest before publication.

CI uses Node.js 24 and pnpm 10.13.1 with a frozen lockfile. Bootstrap playground and example hosts from .env.example, generate ephemeral app keys, and create their tmp directories before host tests. Browser suites require Playwright Chromium and its system dependencies (pnpm --filter playground exec playwright install --with-deps chromium). SQL functional CI covers SQLite, PostgreSQL 14, and MySQL 8.

pnpm lint includes migration SQL-identifier guards, Lucid DateTime query-update guards, and stub-template guards. Scaffolder pack checks exercise the built binary’s help and deterministic dry-run plans for every starter kit, including empty extras and monorepo layout. Upstream starter-layout network tests are opt-in with ADOCOMMERCEKIT_NETWORK_SMOKE=1; ordinary offline tests do not establish upstream availability.

Tagged publication also requires the protected S4_ID30_EVIDENCE and S4_ID31_EVIDENCE secrets. The workflow materializes them as restricted JSON files, runs pnpm s4:release, then publishes through Changesets. The ordinary CI workflow additionally runs a three-dialect upgrade-compatibility matrix and a pack/install job after quality and functional gates.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close