Skip to content

Stage operations

How to operate the stage environment day to day: flip an env var on the legacy core box, take core-api down on purpose, and use the shared smoke accounts and test-data recipes.

Who this is for: developers testing features on stage. Stage has no real customers, ever, so breaking it while you work is acceptable; see Stage is a developer environment. This page replaces per-developer notes: if you learn a durable stage trick, add it here rather than keeping it to yourself.

Related: Branching and Releases, in particular Where did my stage deploy go? and Stage is a developer environment.

Required access

  • AWS: a role in the stage account (258618559895, eu-central-1) allowed ssm:SendCommand and ssm:GetCommandInvocation on the legacy core instance, and ecs:UpdateService on the core cluster.
  • Secrets: none are needed to follow this page. Smoke-account credentials are in the team password manager.
  • VPN / tunnel: none. Access to the instance is through SSM Run Command, not SSH.

Where things are

Thing Value
Legacy core on stage instance i-063f5f4090ef7ad26 (stage-euc1-core-dash), host dash.stage.cookiehub.net
React dashboard on stage dash-next.stage.cookiehub.net (ECS service core-portal)
core-api on stage core-api.stage.cookiehub.net (ECS service core-api, cluster stage-euc1-core-ecs-cluster)
Env file on the instance /home/cookiehub/core/.env, owned by the cookiehub user
AWS account / region 258618559895 / eu-central-1

The instance's .env is not managed by Terraform; it is edited in place. Access is through AWS SSM Session/Run Command (the instance has an SSM agent and IAM role), so no VPN or SSH is needed. Confirm you are on the right account with aws sts get-caller-identity before changing anything. Assume the stage account only; production is never operated this way from a laptop.

Flipping an env var on legacy core

Send a shell command through SSM and read the result back:

aws ssm send-command --region eu-central-1 \
  --instance-ids i-063f5f4090ef7ad26 \
  --document-name AWS-RunShellScript \
  --cli-input-json file://ssm.json

Parameters.commands[0] in the JSON file is a sudo -u cookiehub bash -c '...' (the same shape the core stage deploy workflow uses) that:

  1. edits .env: sed for an existing key; grep -q then append for a new key (a JSON input file avoids shell-escaping trouble);
  2. runs php artisan config:clear.

Then poll aws ssm get-command-invocation until Status=Success and read StandardOutputContent to confirm the edit.

Always config:clear, never config:cache: core has roughly 160 env() calls in application code, and a config cache makes them return null. The deploy script ends in :clear for the same reason.

Simulating a core-api outage

Stage core-api is a single ECS task. To take it down:

aws ecs update-service --region eu-central-1 \
  --cluster stage-euc1-core-ecs-cluster --service core-api --desired-count 0

Within about 30 seconds the load balancer answers 503 (HTML) for every /dash/v1 call. Recover with --desired-count 1; the task is healthy about 20 seconds after it starts (the load balancer answers 401 on /dash/v1/auth/session). No Terraform change is involved; desired_count stays 1 in the stage environment. End any such exercise with a real browser login.

Smoke-test accounts

Credentials for these accounts live in the team password manager, not in this page.

Account Use Notes
smoke+vendor-stage@cookiehub.com, account 104507 "Vendor Smoke Test" (owner) Default account for dashboard and React-dashboard smokes. Email + password login, TOTP off. Not a clean slate any more: it carries several live and soft-deleted domains and subscription rows. Check what is on it before assuming empty.
smoke+dash-next@cookiehub.com React-dashboard auth smokes TOTP was enabled once to exercise 2FA and then disabled so automated smokes can log in with email + password. Re-enable deliberately for a 2FA test.

Use an existing smoke account before creating another. Some accounts reachable from the smoke user are real internal accounts, not fixtures: treat any account that is not 104507 as read-only.

Smoke rule. Any curl or HTTP-client smoke of the React dashboard or /dash/v1 must send Origin: https://<host> on every POST, PUT and DELETE, and a smoke is not complete until one real browser login with the smoke user has been done. Curl alone passed against a surface where every browser POST returned 400 (the framework's CSRF check saw http:// behind the load balancer). "Works without Origin, fails with it" is the signature of a proxy-scheme bug, not CORS.

For HTTP smokes of /dash/v1/*, call core-api.stage.cookiehub.net directly with the dashboard session cookie and the dash-next Origin; the same path through the dash-next hostname is the router's 404 page.

Creating a stage user (SSM tinker)

Do not use model factories on stage. \App\User::factory() chains into \App\Account::factory(), whose definition calls fake(); fake() is only registered when APP_ENV is local or testing, and stage runs as production, so the call fails and nothing is written.

Instantiate the models directly (boot hooks fill users.key and accounts.public_key):

$account = new \App\Account;
$account->name = 'Smoke Test';
$account->save();

$user = new \App\User;
$user->name = 'Smoke Test';
$user->email = 'smoke+xyz@cookiehub.com';
$user->password = \Hash::make('<choose a password; store it in the password manager>');
$user->account_id = $account->id;
$user->email_verified_at = now();   // skip email confirmation
$user->terms = true;
$user->otp_secret = '';             // skip 2FA
$user->save();

\App\AccountUser::add($account->id, $user->id, true);  // owner = true

Assign properties directly: User::$fillable only lists name, email, password, so User::create([...]) would silently drop account_id, email_verified_at and the rest. Name throwaway accounts so they can be found and deleted later (for example " smoke junk (delete me)"), and delete them with a name-guarded tinker command when done.

Users created through core-api's self-serve registration are linked to their account through account_users only; users.account_id is null.

Stage mail is log-only and the log line carries the recipient and subject, never the body, so there is no link to read from the logs. Rebuild it:

$u = \App\User::find(<id>);
echo sha1($u->email . $u->key);   // the `key` in /register/confirmed?id=<id>&key=...

Test-data gotchas on stage

  • Throwaway domain names must resolve in DNS: core-api validates with a live A lookup and has no TLD allowlist. Apex names such as example.com, example.org, example.net pass; subdomains of those do not. <name>.github.io resolves and passes verification.
  • A fresh free domain lands on widget version 2.8.16 (id 225), whose assets are missing from the stage bucket, so publishing fails for it until the domain is moved to a version that exists (tracked as CH-612). A "publish failed" on stage right after creating a domain is usually this, not a code defect.
  • Domain creation triggers a scan; an immediate scan request answers "A scan is already running".
  • Stage's vendor catalogue contains only GVL 3 vendors; use GET /vendor?type=gvl3.
  • A portal deploy to stage starts only after both the CI and Storybook workflows complete on the pushed commit; allow roughly 5 to 8 minutes between a push to stage and the deploy landing.
  • Playwright scripts that import playwright must live inside the repo directory (ESM resolution ignores NODE_PATH); delete them afterwards.
  • dash-next's login form has two submit buttons ("Continue" and "E-mail me a magic link"); target "Continue". Its inputs have no accessible labels, so select by input[type=email] / input[type=password].
  • After a fresh login the current account can be the smoke account or another one the user belongs to; read the current account and switch to 104507 before any write.