Skip to content

instance-setup-demo.md

Latest commit

 

History

History
78 lines (57 loc) · 2.96 KB

instance-setup-demo.md

File metadata and controls

78 lines (57 loc) · 2.96 KB
Raw

Instance Setup: Demo

Create a non-production demonstration installation with 11 dummy staff and a dedicated Xero Demo Company connection.

1. Prepare persistent instance configuration

sudo scripts/server/instance.sh prepare-config <client> uat --seed
sudoedit /opt/docketworks/config/<client>-uat.credentials.env
sudoedit /opt/docketworks/config/<client>-uat.company-defaults.json

Complete the credentials and keep enable_xero_sync false. Leave the demo template's placeholder xero_tenant_id as-is; step 4 rebinds it (see README). This is offline configuration; no DocketWorks services or OAuth flow are involved.

2. Create the instance

sudo scripts/server/instance.sh create <client> uat --seed --no-start

The command loads the configured demo Company/CompanyDefaults and 11 dummy staff without starting gunicorn or Celery. Dummy staff initially have no Xero employee IDs because those IDs belong to a particular Xero tenant.

Verify the bootstrap data:

scripts/server/dw-run.sh <client>-uat python scripts/restore_checks/check_company_defaults.py
scripts/server/dw-run.sh <client>-uat python scripts/restore_checks/check_xero_app.py

3. Authorise Xero Demo Company

Log in as defaultadmin@example.com / Default-admin-password, open Admin > Xero, and complete the existing OAuth flow.

In Admin > Settings, enter demo wording in Xero quote terms that includes the exact text Terms of trade can be found. Copy the same wording to Xero Terms (Quotes). DocketWorks sends its copy on API-created quotes; Xero's copy covers quotes created directly in Xero.

4. Finalise onboarding

scripts/server/dw-run.sh <client>-uat python manage.py finalize_instance_onboarding --seed-xero

The explicit flag may create missing demo-only payroll objects, including the configured weekly calendar and required pay items. It then selects a live branding theme if none is configured, syncs accounts and pay items, links or creates Xero Payroll employees for all dummy staff, creates the nine canonical shop jobs, validates the result, and enables automated sync last.

Failures exit non-zero and leave sync disabled. The command is safe to rerun after correcting the cause.

After a monthly Xero Demo Company reset, run xero --setup --seed-xero; setup discovers the replacement tenant and updates CompanyDefaults and the cache. Restore the matching Xero Terms (Quotes) wording after the reset.

5. Verify

  • Staff list shows 11 demo employees, all linked to Xero Payroll.
  • Exactly nine shop jobs are visible.
  • Admin > Xero reports connected.
  • A normal Xero sync completes without errors.
  • A test job, timesheet, quote, and invoice work as expected.
  • The native Xero PDF for a DocketWorks-created quote contains Terms of trade can be found.

Logins:

  • Admin: defaultadmin@example.com / Default-admin-password
  • Staff: their fixture email / Default-staff-password