bookstore/README.md

Bookstore

WordPress + WooCommerce bookstore. Design reference: see docs/ for the pre-launch plan and the technical design doc (bookstore-core schema, interfaces, order state machine — the design doc is the source of truth for why this repo is laid out the way it is).

Weeks 1–3 of the 5-week plan are done: environments, deploy pipeline, the WooCommerce/HPOS plugin scaffold, catalog schema, Gutenberg importer, pricing engine, membership shipping, checkout, and the order state machine all live under wp-content/plugins/bookstore-core/includes/. Week 4 is narrowed in scope and partially done: a live BooksRun price/stock recheck runs at checkout, but BooksRun AutoBuy and Ingram are deliberately deferred past initial launch (see "What's deliberately not here yet" below).

Layout

docker-compose.yml              base services: db, redis, wordpress, cron
docker-compose.{dev,staging,production}.yml   per-environment overrides (caddy, mailhog)
docker/php/                     app image: WP core image + wp-cli, composer, redis ext
docker/caddy/                   one Caddyfile per environment
docker/cron/                    Action Scheduler driver (system cron has no host to run on in Docker)
deploy/deploy.sh                idempotent bring-up + WP/WooCommerce config
deploy/poll-deploy.sh           host-crontab script: redeploys when its branch moves on Gitea
deploy/backup.sh, restore.sh    off-host backup; restore is staging-only, on purpose
secrets/<env>/                  DB passwords, written fresh by deploy.sh — gitignored, not manually edited
wp-content/plugins/bookstore-core/   the one plugin that owns business logic
wp-content/mu-plugins/          local-mail-catcher.php — routes mail to MailHog outside production

Same code runs in every environment; only .env.<env> and which docker-compose.<env>.yml you layer in differ (design doc §01).

Local development

cp .env.example .env.dev        # fill in DB_PASSWORD etc.; localhost values are fine
make up ENV=dev
make deploy ENV=dev             # installs WP, WooCommerce, activates bookstore-core, enables HPOS

Site is at http://localhost:8080. make wp ENV=dev ARGS="plugin list" runs any wp-cli command; make logs ENV=dev tails everything; make shell ENV=dev drops into the app container.

Staging (this is what goes on your Docker server)

cp .env.example .env.staging
# fill in SITE_DOMAIN, SITE_URL, DB_*
# SITE_DOMAIN must be a HOSTNAME, not a bare IP — see below

make deploy ENV=staging

SITE_DOMAIN needs to be a hostname, not the VM's IP directly. TLS SNI (how Caddy picks which certificate to present) isn't sent for literal IP connections per spec, so HTTPS to a bare IP fails at the handshake itself no matter what Caddy does. Pick any hostname (e.g. bookstore.lan), add it to /etc/hosts (or the Windows equivalent) on whatever machine you're browsing from, pointing at the VM's LAN IP, and use that hostname as both SITE_DOMAIN and in SITE_URL.

Caddyfile.staging forces tls internal — Caddy's own self-signed CA, issued locally with no external network calls — rather than letting Caddy guess whether the name looks "public" (its automatic heuristic only recognizes bare IPs and localhost as obviously-private; anything else, including a made-up LAN hostname, it assumes might be real and tries Let's Encrypt, which then fails). Your browser will show an untrusted-cert warning once; click through it, or trust Caddy's root cert to skip that:

docker compose -p bookstore-staging exec caddy cat /data/caddy/pki/authorities/local/root.crt

Staging is noindex'd (blog_public=0 plus the X-Robots-Tag header in Caddyfile.staging) so search engines won't index it — there's no basic-auth wall on top of that, since this box is LAN-only and not reachable from outside. If that ever changes (a public domain, port-forwarding, etc.), basic-auth is worth adding back before that happens, not after. Mail never leaves the box: it's caught by MailHog, viewable at :8025.

Theme: Blocksy + the Book Store starter site

deploy.sh installs and activates the Blocksy theme and the free Blocksy Companion plugin from wordpress.org automatically — nothing to do here, in any environment.

The Book Store starter site itself is a paid Companion Pro template (Business plan, $99/year — design doc Appendix A), so it can't be scripted against a public API the way the free theme can. One-time manual step per environment, in wp-admin:

1. Purchase/retrieve the Blocksy Business license key.
2. Blocksy → General → License → activate it.
3. Blocksy → Extensions → Starter Sites (Companion Pro) → import Book Store.

After that, the starter site's content and Customizer settings persist in the database like any other WordPress content — a redeploy or a fresh deploy.sh run doesn't touch it or need to repeat it.

Payments: WooCommerce Stripe (authorize/capture)

Deployment installs and activates the official woocommerce-gateway-stripe extension and enables its Issue an authorization on checkout, and capture later setting. Stripe owns card collection, Checkout Block integration, webhooks, authorization, capture, and cancellation; bookstore-core never handles card data or Stripe API credentials.

Set STRIPE_MODE, STRIPE_PUBLISHABLE_KEY, STRIPE_SECRET_KEY, and (when available) STRIPE_WEBHOOK_SECRET in .env.<environment>, then deploy. The deploy script writes them to gitignored Docker secret files and configures the official gateway without printing the credentials. Stripe stays disabled when either API key is missing. Use test keys until checkout, webhooks, capture, and cancellation have been exercised end to end.

For manual API-key connections, create a Stripe webhook endpoint for https://<store-host>/wc-api/wc_stripe, subscribe it to the events recommended by the WooCommerce Stripe settings screen, and place its whsec_... signing secret in STRIPE_WEBHOOK_SECRET. The workflow has seven days from checkout to capture an online card authorization. Manually entered keys do not provide Stripe-to-WooCommerce payment-method synchronization or every feature of the OAuth connection.

An authorized Stripe order arrives as On hold. Order\SupplierOrderJob runs the local fraud extension point, confirms the distributor order, and then changes the order to Processing, which makes the Stripe extension capture the authorization. A distributor failure changes the order to Cancelled so Stripe releases the hold, then routes it to Needs Review.

Admin access restriction (production)

/wp-admin and /wp-login.php can be restricted to specific IPs/CIDR ranges in production via WP_ADMIN_ALLOWED_IPS in .env.production — space-separated, matching Caddy's own remote_ip syntax directly (e.g. 203.0.113.5 198.51.100.0/24). Leave it blank and wp-admin stays reachable from anywhere, same as today — this is opt-in, not on by default, and only applies in production (staging is already LAN-only). /wp-admin/admin-ajax.php is always exempt regardless of the IP list, since WordPress/WooCommerce route some logged-out storefront AJAX through it. Applying a changed value just needs make deploy ENV=production (or restarting the caddy container) — no code change required.

Deploy pipeline

The Git server (Gitea) and the staging/production Docker hosts are separate machines, so instead of a webhook receiver listening for an inbound POST from Gitea, each box just polls its branch and redeploys when it moves — no inbound port to expose or secure.

1. Clone this repo onto the box (e.g. into /srv/bookstore), cp .env.example .env.staging (or .env.production) and fill it in.
2. Add a host crontab entry (not inside a container — crontab -e on the box itself):

   */2 * * * * /srv/bookstore/deploy/poll-deploy.sh staging >> /var/log/bookstore-deploy.log 2>&1
   

   (production + main on the production box.)
3. poll-deploy.sh fetches, compares against the last-deployed commit, and — only if it moved — checks out the branch and runs deploy.sh. Silent otherwise, so it's safe to run every couple of minutes.
4. The box needs its own git credentials to fetch from Gitea (a read-only access token works well) — set those up once via a credential helper or an embedded token in that box's origin remote.

You can also just run ./deploy/deploy.sh <env> by hand at any time; the poll script is only automation on top of the same idempotent script.

Backups

./deploy/backup.sh staging       # or production

Dumps the database and archives wp-content/uploads, gzips both, and syncs to $BACKUP_REMOTE via rclone if set (configure rclone config on the server first — this repo doesn't manage remote credentials). Before launch, run a real restore drill:

./deploy/restore.sh ./backups/production/db-<ts>.sql.gz ./backups/production/uploads-<ts>.tar.gz

restore.sh only ever targets staging — there's no production argument, so a restore drill can't accidentally overwrite the live site.

Catalog pipeline (Week 2)

Staging data is built with wp bookstore sub-commands (see wp bookstore help for full options):

wp bookstore import-gutenberg --limit=10000   # Work/Edition/ISBN rows from the real PG catalog feed
wp bookstore generate-offers                  # synthetic SupplierOffer rows: stock, condition, price
wp bookstore sync-products                    # one WooCommerce product per Work
wp bookstore sync-covers --limit=20           # optional: real cover art via Open Library
wp bookstore sync-hardcover-tags --limit=20   # optional: genre/mood/content-warning tags

import-gutenberg --limit counts only new titles per run, so re-running with a bigger --limit continues forward instead of rescanning. Pricing (25% target margin) and the $25/$15 free-member shipping thresholds are in includes/Pricing/PricingEngine.php and includes/Shipping/BSC_Free_Shipping.php.

Checkout + order engine (Week 3, payment flow revised)

A synchronous supplier/margin recheck runs right before payment (Order\CheckoutRecheck, price/margin only — never charges anything). The official WooCommerce Stripe extension then holds the card and its On-hold transition runs the fraud check (Payments\FraudCheck) before moving the order to bsc-authorized (held, not charged). Order\SupplierOrderJob picks it up from there: submits to the supplier, and only on success captures the hold (the card is actually charged for the first time here) before moving to bsc-ordered → bsc-shipped → completed. Any failure at any stage — no sellable offer, margin no longer holds, fraud check fails, or the supplier submission itself fails — lands the order in bsc-exception ("Needs Review"), which is the review queue: just a filterable WooCommerce order status, not a separate table. Because nothing is charged until capture, most failures are a void (AuditTrail::record_void(), zero cost) rather than a refund — a refund only happens for the rarer case of something going wrong after a real capture.

wp bookstore force-offer-status <isbn13> <active|stale|discontinued> (see wp bookstore help) forces a specific ISBN's synthetic offer into a specific state — SyntheticOfferGenerator's rolls are random, so this is how to reliably exercise the recheck's failure paths (price-increase, out-of-stock, discontinued-after-supplier-submission) in a real checkout.

Real BooksRun/Ingram supplier adapters are still Week 4 — SupplierOrderJob runs against the synthetic gutenberg_test supplier for now, deliberately built through the same Action Scheduler/locking path Week 4's real integration will reuse rather than restructure.

Testing

make test ENV=dev

Runs bookstore-core's PHPUnit suite (wp-content/plugins/bookstore-core/tests/) against pure business logic — currently the 25% pricing formula (Pricing\PricingEngine) and the $25/$15 free-shipping thresholds (Shipping\BSC_Free_Shipping) — using Brain Monkey/Mockery to stub WordPress/WooCommerce rather than a full WP-integration bootstrap. First run installs dev dependencies via Composer inside the wordpress container; since the bind-mounted plugin directory is host-owned and www-data can't write into it, that install step runs as root and then chowns vendor//composer.lock back to the host user (see the test target's comment in Makefile). Not yet covered: Order\CheckoutRecheck and the order state machine.

What's deliberately not here yet

• BooksRun AutoBuy and Ingram supplier adapters — deliberately deferred; SupplierOrderJob still submits synthetic (gutenberg_test) orders only. The BooksRun price/stock recheck itself is live (see "Checkout
  • order engine" above) — it's just automated purchase submission and Ingram entirely that aren't built.
• The daily BooksRun FTP bulk-sync job's scheduling/dedup/batch-write infrastructure is real (Import\BooksRunOfferSync), but actually connecting to a live feed is a deliberate stub — no FTP access or sample feed exists yet to build the parser against.
• Automated tests for the checkout-recheck/order-state-machine logic — the pricing formula and shipping thresholds now have tests (see "Testing" above), but Order\CheckoutRecheck and the state machine itself don't yet.
• A real TLS-terminating public domain — Caddy will auto-provision certs once SITE_DOMAIN points at a real host with 80/443 reachable; until then docker-compose.dev.yml is the only one that works from localhost.
• CI automation — make test runs the suite manually, but nothing wires it into the deploy pipeline (poll-deploy.sh) yet, so a broken test doesn't block a deploy.