Skip to main content

Dockerless PostgreSQL

Scope This guide only applies to GitHub Copilot's Codex (or similar managed) sandboxes where Docker is disabled. These scripts are not meant for normal local workstations; if you have Docker available, follow the standard workflow in Local Development instead.

The repository ships a thin wrapper around the system PostgreSQL packages so that integration tests and local tooling work in Dockerless sandboxes. The scripts live under scripts/ and are idempotent, so you can run them whenever the environment is reset.

One-time bootstrap​

sudo ./scripts/codex-setup.sh

Run this only inside the Codex VM (the script auto-detects the /workspace/Hephaestus checkout). If detection ever fails, pass HEPHAESTUS_ROOT=/workspace/Hephaestus explicitly.

What the script does:

  • Installs PostgreSQL server/client packages via apt-get when they are missing.
  • Installs top-level npm dependencies (npm install).
  • Bootstraps the shared Python tooling (npm run bootstrap:py).
  • Creates and initialises a managed database cluster in server/application-server/postgres-data-local/ using scripts/local-postgres.sh.

If sudo is unavailable, run the script as the root user. The script exits early rather than attempting a partial install.

Daily maintenance​

Codex reboots the VM between sessions, so use the lightweight helper whenever the sandbox wakes up from cold storage:

./scripts/codex-maintenance.sh

It ensures the local cluster is running (scripts/local-postgres.sh start) and refreshes npm dependencies with cached modules (npm install --prefer-offline).

Database helpers and tests​

  • All npm run db:* utilities automatically fall back to the managed cluster when Docker is missing. Set HEPHAESTUS_DB_MODE=local to force that behaviour even on hosts that have Docker installed.
  • The Maven Surefire/Failsafe configuration extends the fork timeout to 180 seconds when HEPHAESTUS_DB_MODE=local, giving the local cluster enough time to warm up during integration tests.
  • The integration-test harness (PostgreSQLTestContainer) connects to the managed cluster whenever Docker is unavailable.

Manual control​

You can manage the database directly:

scripts/local-postgres.sh status   # check
scripts/local-postgres.sh stop     # free port 5432
scripts/local-postgres.sh start    # restart after stop

The script reuses the system PostgreSQL binaries provided in the Codex base image. On Codex sandboxes without a postgres user it runs the cluster under the invoking user; on Linux desktops it would fall back to runuser/su, but local machines should rely on Docker instead.

Limitations​

  • Keycloak and the remaining Docker Compose services still require Docker.
  • scripts/local-postgres.sh expects PostgreSQL 14+ binaries (pg_ctl, pg_isready). Run ./scripts/codex-setup.sh if commands are missing.
  • Always stop the cluster when you finish (scripts/local-postgres.sh stop) to leave port 5432 free for other workflows.