00 — Run Amber locally with demo data

For whoever prepares a demo or a training session. You need to be comfortable with a terminal. Staff using Amber can skip to chapter 01.

1. How the demo works#

docs/tools/start-demo.sh
   ├── PostgreSQL database  amber_docs   (separate from your normal amber_pos)
   ├── mail catcher         127.0.0.1:1025 → docs/tools/.mail/*.eml
   ├── API (backend/)       http://localhost:3001
   └── POS (frontend/)      http://localhost:3000   ← open this in the browser

• The demo uses its own database, amber_docs. Your usual backend/.env database is not touched.
• On first start the API fills the database with demo data: the admin, three waiters, two cashiers, two menus (Main meals, Drinks) with 20 dishes, stores, stock categories and the role PINs.
• Emails (staff invites, password resets) are not sent. A small mail catcher saves them as files in docs/tools/.mail/, so you can read the temporary password in an invite.
• The rest of the demo story (suppliers, stock, a sale) is added by following chapters 02–08, by hand or with the recording scripts.

2. Before you start#

The script connects to PostgreSQL as your computer user, without a password (the default for a Homebrew install on a Mac). If your PostgreSQL needs a password, set it before starting:

export PGPASSWORD=postgres
export DEMO_DATABASE_URL='postgresql://postgres:postgres@localhost:5432/amber_docs?schema=public'

Ports 3000, 3001 and 1025 must be free. Stop your normal pnpm dev / pnpm start:dev first.

3. Start the demo#

From the repository root:

bash docs/tools/start-demo.sh --reset

--reset deletes the demo database and starts clean. Leave it out to keep the data from last time. When you see this, open http://localhost:3000:

Amber is ready: http://localhost:3000
Admin PIN 1234 · Manager 2580 · Cashier 4321 · Waiter 1111 · Kitchen 7834 · Store 5566
Press Ctrl+C to stop.

Ctrl+C stops everything. Logs are in docs/tools/.logs/ (backend.log, frontend.log, mail.log).

The admin can also sign in by email: admin@amberdemo.com, password Admin123!.

4. Open this guide as a website#

The guide reads fine on GitHub, but it is easier to use as a website with search, a chapter list, videos that play on the page, and a light/dark switch. From the repository root:

(cd docs/tools && npm install)   # once
node docs/tools/serve-docs.mjs

Then open http://localhost:4000. Use PORT=4100 in front of it if 4000 is taken. Press / to jump to the search box.

The published guide is at https://docs.majlisalarabi.com. After changing pages, screenshots or videos, publish them with:

bash docs/tools/deploy-docs.sh

It copies the pages, images, videos and the docs server to /var/www/amberdocs on the server and restarts the pm2 app amber-docs (port 3040, behind nginx with HTTPS). The recording scripts, snapshots, logs and caught demo emails are not copied.

5. Save and restore the data#

To go back to a known point, for example before a training session, save a snapshot and restore it later. The demo can keep running while you do this.

bash docs/tools/snapshot.sh save before-training
bash docs/tools/snapshot.sh load before-training

The recording script saves after-01 … after-08 as it goes, so you can start a session at the beginning of any chapter: bash docs/tools/snapshot.sh load after-05 gives you the state at the start of chapter 06.

6. Record the videos and screenshots again#

After Amber changes, make the screenshots and videos again so the guide matches the screens.

1. Once: install the recording tools.

   cd docs/tools
   npm install
   npx playwright install chromium

2. Start the demo from a clean database: bash docs/tools/start-demo.sh --reset.

3. In a second terminal, record everything:

   bash docs/tools/record-all.sh

   A browser window opens and works through each chapter slowly, with step captions. Don't use the mouse in that window while it records. All eight chapters take about 30 minutes. Screenshots go to docs/images/<chapter>/, videos to docs/videos/<chapter>.mp4.

To redo one chapter, give its number: bash docs/tools/record-all.sh 06. It restores the data from the end of chapter 05 first.

To check quickly that the scripts still match the screens, without a visible browser or video: FAST=1 bash docs/tools/record-all.sh. This replaces the screenshots, but not the videos.

7. Common problems#

Checklist#

• bash docs/tools/start-demo.sh --reset prints Amber is ready
• http://localhost:3000 shows the Amber welcome screen
• Admin PIN 1234 opens the Admin dashboard with six team members
• A snapshot saves and loads without errors