A script to start the local environment for testing and review #125

New Issue

2026-08-22T11:03:10-05:00

bermudalamb commented

2026-08-22 11:03:10 -05:00

Bringing the app up locally is currently seven or eight commands that have to be got right in order, and getting one wrong fails somewhere unhelpful. A Postgres container on a port that is not blocked, the six environment variables the backend refuses to boot without, migrations, a TypeScript build, the backend process, then the Vite dev server.

None of it is hard. All of it is tedious, easy to get subtly wrong, and undocumented outside CI workflows that are written for a Linux runner rather than a Windows workstation.

What it should do

scripts/start-local.ps1, run from anywhere in the repository:

Check Docker is running, and say so plainly if it is not, rather than failing later inside a docker run.
Create or reuse a named Postgres container, wait for pg_isready rather than sleeping a fixed number of seconds.
Install dependencies if node_modules is missing, and skip that step otherwise.
Run migrations, build the backend, start it with the environment it requires, and wait for /api/config to answer 200 before continuing.
Start the Vite dev server.
Print the URLs and where the logs went.

Switches: -Fresh to drop and recreate the database, -Stop to tear everything down, and -DbPort / -ApiPort to move off a conflicting port.

The port thing specifically

55432 is reserved by Hyper-V on at least one machine here, and the failure it produces when Docker cannot bind is not obviously a port reservation. The script should default to a port outside the usual range and, when a bind fails, say what happened and name the switch that moves it. This has cost time more than once.

Verification

The test is that it works from a cold start: no container, no node_modules, nothing listening. Run it, then load the storefront and sign in. Then run it a second time with everything already up, and confirm it is idempotent rather than erroring on the container that already exists. Then -Stop, and confirm nothing is left listening on either port.

Bringing the app up locally is currently seven or eight commands that have to be got right in order, and getting one wrong fails somewhere unhelpful. A Postgres container on a port that is not blocked, the six environment variables the backend refuses to boot without, migrations, a TypeScript build, the backend process, then the Vite dev server. None of it is hard. All of it is tedious, easy to get subtly wrong, and undocumented outside CI workflows that are written for a Linux runner rather than a Windows workstation. ## What it should do `scripts/start-local.ps1`, run from anywhere in the repository: - Check Docker is running, and say so plainly if it is not, rather than failing later inside a `docker run`. - Create or reuse a named Postgres container, wait for `pg_isready` rather than sleeping a fixed number of seconds. - Install dependencies if `node_modules` is missing, and skip that step otherwise. - Run migrations, build the backend, start it with the environment it requires, and wait for `/api/config` to answer 200 before continuing. - Start the Vite dev server. - Print the URLs and where the logs went. Switches: `-Fresh` to drop and recreate the database, `-Stop` to tear everything down, and `-DbPort` / `-ApiPort` to move off a conflicting port. ## The port thing specifically 55432 is reserved by Hyper-V on at least one machine here, and the failure it produces when Docker cannot bind is not obviously a port reservation. The script should default to a port outside the usual range and, when a bind fails, say what happened and name the switch that moves it. This has cost time more than once. ## Verification The test is that it works from a cold start: no container, no `node_modules`, nothing listening. Run it, then load the storefront and sign in. Then run it a second time with everything already up, and confirm it is idempotent rather than erroring on the container that already exists. Then `-Stop`, and confirm nothing is left listening on either port.

bermudalamb referenced this issue from a commit

2026-08-22 11:09:10 -05:00

feat(scripts): a PowerShell script to start the local environment (#125)

bermudalamb referenced a pull request that will close this issue

2026-08-22 11:10:21 -05:00

feat(scripts): a PowerShell script to start the local environment (#125) #126

bermudalamb self-assigned this 2026-08-22 11:11:43 -05:00

bermudalamb added this to the Code Quality and Hardening 2 project 2026-08-22 11:11:48 -05:00

bermudalamb moved this to Review in Code Quality and Hardening 2 on 2026-08-22 11:11:52 -05:00

bermudalamb closed this issue

2026-08-22 11:12:17 -05:00

bermudalamb referenced this issue from a commit