How do I ready up an environment?

How do I ready up an environment: confirm a recent database (recreating only if needed), start services, provision the tenant, and optionally start the client?

1. Check whether the database is already recent — never recreate unconditionally; a fresh recreate + re-provision costs real minutes, so only pay for it when the check says to:

   ./projects/ores.compass/compass.sh db status
   

   Recreate if drift is not current, if built from predates the commit you're testing against, or if you're simply not sure the schema reflects the change under test. If the acme_corporation tenant already shows [active] and the database is current, skip straight to step 4 (services) — steps 2-3 are not needed.

2. Stop services before recreating (safe to run even if none are up):

   ./projects/ores.compass/compass.sh services stop
   

3. Recreate the database — drops and rebuilds roles, schema, and seed data from scratch:

   ./projects/ores.compass/compass.sh db recreate -y -k
   

4. Start services — NATS and all backend services:

   ./projects/ores.compass/compass.sh services start
   

   Verify everything came up:

   ./projects/ores.compass/compass.sh services status
   

5. Provision the tenant yourself, via ores.shell — the default is the Acme Corporation holding-group tenant, the system's reference fully-populated test/demo entity (parties, business units, portfolios, books, staff accounts with photos, GLEIF counterparties). Unless the user asks for a different tenant (e.g. the synthetic Acme provisioner, see How do I provision the system with Acme (synthetic)?), run this yourself — never hand it to the user:

   ./projects/ores.compass/compass.sh shell -f \
     projects/ores.shell/scripts/library/provisioning/how_do_i_provision_the_system_with_acme_corporation_holding_group.ores
   

   Any failure here must be diagnosed and fixed before continuing — do not proceed against a partially-provisioned tenant, and do not hand a broken environment to the user to work around. A provisioning failure is frequently a real bug (schema drift, a stale DQ-publish function, a type mismatch) rather than an environment problem; fix the underlying cause, redeploy the changed SQL, and re-run from step 3 (a fresh db recreate) until it completes cleanly. If it fails instead with a Postgres "remaining connection slots are reserved" error, see How do I solve the postgres max connections error? — another environment on the shared instance is usually holding excess connections; diagnose before assuming this environment is at fault.

6. Start the client — only if the caller needs a bare, unscripted client. Skip this step entirely if what you actually need is a client with a test scenario preloaded (--open-scenario, an absolute path via realpath) — start it directly with that flag instead of starting a bare client here and restarting it later; see Devops Run Client.

   ./projects/ores.compass/compass.sh client start --colour <colour>
   

   Detached, with a distinct colour so it does not clash with other environments' running instances. The instance name is always this environment's own ORES_CHECKOUT_LABEL (e.g. jolly_knuth) — not overridable — so the status bar and window title always show which environment the client actually belongs to. Log in with the super_admin credentials used in the provisioning step (or the tenant admin credentials, once a tenant party is selected).

No single wrapper script — each step delegates to its own compass subcommand (services, db, shell -f, client); this recipe is the sequencing.

Manual: run the full sequence against a fresh checkout and confirm the client logs in and lists Acme Corporation party data.

• How do I start the ORE Studio services?
• How do I recreate the database?
• How do I provision the system with Acme Corporation (holding group)?
• How do I provision the system with Acme (synthetic)?
• How do I provision a tenant?
• How do I solve the postgres max connections error?
• Devops Run Client — --open-scenario mechanics for step 6's alternative.
• How do I test a feature after implementation? — calls this recipe.
• How do I capture screenshots for a manual chapter? — calls this recipe.