docker-compose.prod.yml

@@ -51,12 +51,14 @@
 # Portainer's stack variables are substituted into this file; they are not
 # handed to the container. A variable set in Portainer with no line here never
 # reaches the app, and the failure reads as "I set it and it says it is not
-# set". Only secrets are interpolated below, because only secrets have a reason
-# not to be in the repository. Everything else is written out, so there is one
-# place to look and one thing that can be wrong.
+# set". Secrets are interpolated below, because they have a reason not to be in
+# the repository — and so is DEMO_MODE, which is not a secret but is the one
+# value that gets flipped without a code change, which is a reason of its own
+# (#190). Everything else is written out, so there is one place to look and one
+# thing that can be wrong.
 #
-# Required stack environment variables — all secrets, all must be set in
-# Portainer for this stack:
+# Required stack environment variables. All must be set in Portainer for this
+# stack. All are secrets except DEMO_MODE:
 #
 #   DEMO_MODE             `true` or `false`, exactly. Whether real payments are
 #                         taken. Not a secret — it is here rather than written
@@ -74,9 +76,11 @@
 #                         See #63. Without it, /api/admin is protected only by
 #                         the proxy — anything reaching the container directly
 #                         can administer the store.
-#   PAYPAL_CLIENT_ID      Live PayPal credentials. Required because DEMO_MODE is
-#   PAYPAL_CLIENT_SECRET  false below; the app refuses to start without them.
-#   PAYPAL_WEBHOOK_ID
+#   PAYPAL_CLIENT_ID      Live PayPal credentials. Required when DEMO_MODE is
+#   PAYPAL_CLIENT_SECRET  `false`; the app refuses to start without them rather
+#   PAYPAL_WEBHOOK_ID     than pretending it can take payments. Unused while
+#                         DEMO_MODE is `true`, so flipping it to `false` without
+#                         them crash-loops the container.
 #   BACKUP_PASSPHRASE     Optional. Set it and the uploads archives are
 #                         encrypted at rest; leave it empty and they are not.
 #                         See docs/ops/backup-and-restore.md before setting it —

docs/ops/production-stack-cutover.md

@@ -60,7 +60,9 @@ Everything here is lost when the stack is deleted, and the rollback in step 8 is
 
 **The stack name**, exactly as Portainer shows it. If it is not `redefined-designs`, note that — the new stack must be created with that name, because the stack name becomes the compose project name and reusing QA's would make Compose reconcile the two against each other.
 
-**Every stack environment variable, name and value.** These are all secrets, they belong to the stack, and deleting it discards them. This is the step whose omission is felt hardest: the compose file interpolates `DB_PASSWORD`, `SMTP_USER`, `SMTP_PASSWORD`, `SMTP_FROM`, `ADMIN_GATE_SECRET`, `PAYPAL_CLIENT_ID`, `PAYPAL_CLIENT_SECRET` and `PAYPAL_WEBHOOK_ID`, and an unset one substitutes to an empty string rather than failing. A missing `DB_PASSWORD` cannot authenticate against its own data directory; a missing PayPal secret crash-loops the container, because `DEMO_MODE` is false here and the app refuses to pretend it can take payments. Neither is recoverable from anything in this repository.
+**Every stack environment variable, name and value.** They belong to the stack, and deleting it discards them. This is the step whose omission is felt hardest: the compose file interpolates `DEMO_MODE`, `DB_PASSWORD`, `SMTP_USER`, `SMTP_PASSWORD`, `SMTP_FROM`, `ADMIN_GATE_SECRET`, `PAYPAL_CLIENT_ID`, `PAYPAL_CLIENT_SECRET` and `PAYPAL_WEBHOOK_ID`, and an unset one substitutes to an empty string rather than failing. A missing `DB_PASSWORD` cannot authenticate against its own data directory, and none of this is recoverable from anything in this repository.
+
+`DEMO_MODE` is the odd one out and the easiest to miss, because it is the only one that is not a secret. It must be exactly `true` or `false`. There is no default in the compose file, deliberately (#190) — a default would decide whether the shop takes money on the operator's behalf, silently, whichever way it pointed — so an unset `DEMO_MODE` refuses to boot rather than guessing. Production is `true` for now, the interim from #191; setting it to `false` is what restores real payments, and doing that without all three PayPal secrets present crash-loops the container.
 
 Copy them somewhere before you delete anything.
 
@@ -217,7 +219,16 @@ Migration output must appear *before* `listening on 3000`, and `listening on 300
 - `MAIL_ALLOWLIST is not set` — production is the one environment that has to reach real customers.
 - `UPLOADS_BASE_URL is not set` — the uploads origin is not configured yet (#103). Expected until an NPM host exists for it.
 
-**What a crash loop looks like, and it is the likeliest outcome of a missed step 2.** A `[config] refusing to start` block, then the whole boot sequence again, repeating:
+**What a crash loop looks like, and it is the likeliest outcome of a missed step 2.** A `[config] refusing to start` block, then the whole boot sequence again, repeating.
+
+While production is in the demo interim, the likeliest one is `DEMO_MODE` itself:
+
+```
+[config] refusing to start — 1 problem(s) with the environment:
+[config]   - DEMO_MODE is required and must be exactly 'true' or 'false'.
+```
+
+The other form appears once `DEMO_MODE` is `false` and real payments are on:
 
 ```
 [config] refusing to start — 3 problem(s) with the environment:
@@ -226,9 +237,11 @@ Migration output must appear *before* `listening on 3000`, and `listening on 300
 [config]   - PAYPAL_WEBHOOK_ID is required when DEMO_MODE=false, because real payments are enabled.
 ```
 
-That is a secret that did not reach the container, and it is what happens when the stack variables recorded in step 2 were not carried across — they belong to the stack and were discarded with the old one. An unset stack variable substitutes to an empty string rather than failing, so the container receives `PAYPAL_CLIENT_ID=` and refuses it.
+Either way it is a stack variable that did not reach the container, and it is what happens when the ones recorded in step 2 were not carried across — they belong to the stack and were discarded with the old one. An unset stack variable substitutes to an empty string rather than failing, so the container receives `PAYPAL_CLIENT_ID=` and refuses it.
 
-Read the list against the compose file to tell a missing variable from a misnamed one. Anything hardcoded there — `PAYPAL_ENV`, `DEMO_MODE`, `UPLOADS_DIR` — cannot be missing, so its absence from the error list proves nothing. What is diagnostic is an *interpolated* variable that is NOT in the list: if `ADMIN_GATE_SECRET` is quiet while the PayPal three complain, substitution is working and those three specifically are unset, rather than something being wrong with the stack.
+Compose itself only warns about this — `The "DEMO_MODE" variable is not set. Defaulting to a blank string.` — and deploys anyway. That warning is easy to miss in Portainer's stack UI, and the container then crash-loops under `restart: unless-stopped`: loud in the log, invisible in a glance at the stack list. The container log is the reliable signal, not the deploy output.
+
+Read the list against the compose file to tell a missing variable from a misnamed one. Anything hardcoded there — `PAYPAL_ENV`, `UPLOADS_DIR` — cannot be missing, so its absence from the error list proves nothing. `DEMO_MODE` was in that list and is not any more: since #190 it is interpolated like the secrets, which makes it the first thing to check rather than something to rule out. What is diagnostic is an *interpolated* variable that is NOT in the list: if `ADMIN_GATE_SECRET` is quiet while the PayPal three complain, substitution is working and those three specifically are unset, rather than something being wrong with the stack.
 
 Fix it in the stack's environment, under exactly the names the compose file reads, and redeploy. If the values are gone with the old stack, the client id and secret are in the PayPal developer dashboard under the live app, and the webhook id is on the webhook entry for `PUBLIC_URL/webhooks/paypal` — readable rather than only recreatable.
 

frontend/src/cart/Cart.tsx

@@ -5,6 +5,7 @@ import List from 'antd/es/list';
 import Button from 'antd/es/button';
 import Empty from 'antd/es/empty';
 import Card from 'antd/es/card';
+import Alert from 'antd/es/alert';
 import Radio from 'antd/es/radio';
 import Form from 'antd/es/form';
 import Input from 'antd/es/input';
@@ -128,7 +129,10 @@ export default function Cart() {
     setCheckingOut(true);
     try {
       await demoCartPurchase(selectedAddressId);
-      message.success('Order complete!');
+      // The item really is marked sold and everyone who favorited it really is
+      // emailed, so the one moment the customer is told what happened is the one
+      // moment a demo order has to stop looking like a real one. #195.
+      message.success('Demo order complete — nothing was charged and nothing will be shipped.');
       refreshCartContext();
       loadAll();
     } catch (err) {
@@ -235,17 +239,38 @@ export default function Cart() {
             </Card>
 
             <Card title="Checkout" style={{ marginTop: 24 }}>
+              {/*
+                Shown for the whole of demo mode: before an address is picked,
+                and whether or not PayPal is configured. The word on the button
+                is the smaller half of this — it asks the customer to notice a
+                parenthesis on the control they have already decided to press.
+              */}
+              {config?.demoMode && (
+                <Alert
+                  type="warning"
+                  showIcon
+                  style={{ marginBottom: 12 }}
+                  message="Demonstration only"
+                  description="This shop is not taking payments at the moment. Placing an order here costs nothing, and nothing will be shipped."
+                />
+              )}
               {!selectedAddressId && <Text type="warning">Select a shipping address to check out.</Text>}
               {config?.paypalClientId && selectedAddressId && <div id="paypal-cart-buttons" />}
               {config?.demoMode && selectedAddressId && (
                 <Button
                   block
+                  // Secondary when real PayPal buttons sit above it, primary when
+                  // it is the only way to check out. The label does not follow
+                  // that: a demo order is a demo order either way, and gating the
+                  // word on a PayPal client id meant production — which runs demo
+                  // mode precisely because it has no PayPal credentials — was the
+                  // one place the label never appeared. #195.
                   type={config.paypalClientId ? 'default' : 'primary'}
                   style={{ marginTop: 8 }}
                   loading={checkingOut}
                   onClick={handleDemoCheckout}
                 >
-                  {config.paypalClientId ? 'Checkout (Demo)' : 'Checkout'}
+                  Checkout (Demo)
                 </Button>
               )}
             </Card>

frontend/tests/e2e/demo-checkout.spec.ts

@@ -0,0 +1,80 @@
+import { test, expect, createItem, uniqueSuffix } from './fixtures';
+
+/**
+ * Demo mode as production actually runs it: `DEMO_MODE=true` with no PayPal
+ * credentials configured, which is the interim #191 put in place and the shape
+ * this suite already runs in.
+ *
+ * That combination used to render a full-width primary button reading plainly
+ * "Checkout". The "(Demo)" suffix was gated on a PayPal client id being present,
+ * so the one configuration that needs the label was the only one that did not
+ * get it — and the button is not decorative, it marks real inventory sold and
+ * emails everyone who favorited it. See #195.
+ *
+ * These assert what a customer can see, because that is the whole defect. The
+ * server was always right about what it was doing.
+ */
+
+const ADDRESS = {
+  fullName: 'Dana Holt',
+  addressLine1: '118 Cedar Street',
+  city: 'Asheville',
+  state: 'NC',
+  postalCode: '28801',
+  isDefault: true
+};
+
+test.describe('Demo mode says so to the customer', () => {
+  test('labels the checkout button as a demo when no PayPal is configured', async ({
+    page,
+    customer,
+    cart
+  }) => {
+    const name = `Demo c${uniqueSuffix()}`;
+    const item = await createItem(page.request, { name, price: '80' });
+    expect((await page.request.post(`/api/cart/items/${item.id}`)).status()).toBe(201);
+    expect((await page.request.post('/api/customers/me/addresses', { data: ADDRESS })).ok()).toBe(true);
+
+    await cart.goto();
+
+    // The cart selects the default address on load, so the checkout controls
+    // render with nothing clicked.
+    await expect(cart.checkoutButton).toBeVisible({ timeout: 20000 });
+    await expect(cart.checkoutButton).toHaveText('Checkout (Demo)');
+  });
+
+  test('says so before the customer commits, not only on the button', async ({
+    page,
+    customer,
+    cart
+  }) => {
+    const name = `Demo n${uniqueSuffix()}`;
+    const item = await createItem(page.request, { name, price: '80' });
+    expect((await page.request.post(`/api/cart/items/${item.id}`)).status()).toBe(201);
+    expect((await page.request.post('/api/customers/me/addresses', { data: ADDRESS })).ok()).toBe(true);
+
+    await cart.goto();
+
+    // A label on the button alone asks the customer to notice a parenthesis on
+    // the thing they are already clicking. The notice is the part that has to
+    // survive someone not reading carefully.
+    await expect(cart.demoNotice).toBeVisible({ timeout: 20000 });
+  });
+
+  test('the confirmation says nothing was charged', async ({ page, customer, cart }) => {
+    const name = `Demo p${uniqueSuffix()}`;
+    const item = await createItem(page.request, { name, price: '80' });
+    expect((await page.request.post(`/api/cart/items/${item.id}`)).status()).toBe(201);
+    expect((await page.request.post('/api/customers/me/addresses', { data: ADDRESS })).ok()).toBe(true);
+
+    await cart.goto();
+    await expect(cart.checkoutButton).toBeVisible({ timeout: 20000 });
+
+    await cart.checkoutButton.click();
+
+    // "Order complete!" is true and is exactly what a real order would say. The
+    // item really is marked sold and favoriters really are emailed, so the one
+    // moment the customer is told what happened has to distinguish the two.
+    await expect(page.getByText(/nothing was charged/i)).toBeVisible({ timeout: 20000 });
+  });
+});

frontend/tests/e2e/pages/CartPage.ts

@@ -10,10 +10,18 @@ import { Locator, Page } from '@playwright/test';
 export class CartPage {
   readonly continueShoppingButton: Locator;
   readonly emptyNotice: Locator;
+  readonly checkoutButton: Locator;
+  readonly demoNotice: Locator;
 
   constructor(private readonly page: Page) {
     this.continueShoppingButton = page.getByRole('button', { name: 'Continue Shopping' });
     this.emptyNotice = page.getByText('Your cart is empty');
+    // Matched on a prefix rather than the whole label, so a test can assert what
+    // the label says instead of having to know it in order to find the button.
+    // That is the point of #195: the label was wrong, and a locator naming it in
+    // full would have gone looking for the right button and found nothing.
+    this.checkoutButton = page.getByRole('button', { name: /^Checkout/ });
+    this.demoNotice = page.getByText('Demonstration only');
   }
 
   async goto(): Promise<void> {