Skip to content

QUICK-START.md

Latest commit

 

History

History
146 lines (99 loc) · 5.89 KB

QUICK-START.md

File metadata and controls

146 lines (99 loc) · 5.89 KB
Raw

Quick Start

Shortest path from a fresh clone to a running local instance. Two options: API + web on host (with Postgres and Valkey in Docker) or everything in Docker. Uses Make where possible.

Prerequisites

  • Docker (required for both paths)
  • Make
  • Node.js 24+ (only for “on host” path; e.g. nvm use or direnv allow if using the repo flake)

LLM / editor guidance

.cursor/ and .cursorrules are the source of truth for AI assistants. See docs/development/llm/DOCS-DEVELOPMENT-LLM.md.

Path A: API and web on host (Postgres and Valkey in Docker)

git clone <repo-url> metaboost && cd metaboost
npm install
make local_env_setup

If you add or change dependencies later, run ./scripts/development/update-lockfile-linux.sh (requires Docker) and commit the updated package-lock.json so CI stays green. See Lockfile (Linux).

Prepare and link are not required; secrets are auto-generated by make local_env_setup. See docs/development/env/LOCAL-ENV-OVERRIDES.md.

apps/api/.env is set for API-on-host: DB_HOST=localhost, DB_PORT=5532, KEYVALDB_HOST=localhost, KEYVALDB_PORT=6479 (so the API on your machine talks to Postgres/Valkey in Docker).

make local_infra_up
make local_db_init
npm run dev:all

(make local_setup runs local_env_setup, local_infra_up, and local_db_init in one go—use it instead of the two Make lines above if you prefer.)

Local dev login

After make local_db_init, the main web app has a seeded account:

  • Email: localdev@example.com
  • Password: Test!1Aa

Management-web requires a superuser from make local_management_superuser_create (default username superuser, password Test!1Aa).

If the browser loops between /login and /dashboard or logs SecurityError on history API calls, clear site cookies for http://localhost:4002 (remove api_session and api_refresh) and use localhost consistently (not 127.0.0.1). See INFRA-DOCKER-LOCAL.md for infra details.

make local_env_setup seeds apps/web/sidecar/.env and apps/management-web/sidecar/.env from canonical template defaults plus overrides; infra/config/local/*-sidecar.env remains Docker Compose-only. See LOCAL-ENV-OVERRIDES.md.

To run with auto-rebuild on file changes:

npm run dev:all:watch

Path B: Everything in Docker

Same clone and env setup, then run the full stack (API, web, sidecar, Postgres, Valkey) in containers. The sidecar is not exposed to the host; only the web container uses it.

git clone <repo-url> metaboost && cd metaboost
make local_env_setup
make local_all_up
make local_db_init

Alternatively: make local_setup (env + infra + DB init), then make local_apps_up or make local_apps_up_build—starts app containers without bringing Postgres up twice.

Teardown is the same as Path A: make local_down.

Full nuke rebuild (all apps in Docker)

For a from-scratch local stack—tear down volumes, regenerate env, rebuild images, and start Postgres, Valkey, pgAdmin, and all app containers (API, web, sidecars, management API, management web)—use:

make local_nuke_rebuild_run

(Use SUPERUSER_ARGS for non-interactive setup, for example make local_management_superuser_create SUPERUSER_ARGS="-u superuser --random-password". In Metaboost this target runs in a temporary Docker container on metaboost_local_network, so DB hostnames like postgres resolve consistently.)

This differs from make local_setup, which brings up infra and DB (local_env_setup, local_infra_up, local_db_init) but does not start app containers—use it for host dev (npm run dev:all) after a single Make chain. Use local_nuke_rebuild_run when you want every service, including API and web, running in Docker.

Teardown

Stop and remove containers and network (volumes are kept; Postgres and Valkey data persist):

make local_down

To also remove volumes (e.g. for a clean DB and Valkey state), use either:

make local_down_volumes

or the combined full teardown:

make local_clean

(local_clean runs local_down then local_down_volumes.) The next time you start Postgres with an empty data volume, init scripts run again on first boot; then run make local_db_init for migrations and the dev seed user.

Clean restart

To tear down and start again:

  • Path A: make local_down then make local_infra_up, make local_db_init, and npm run dev:all
  • Path B: make local_down then make local_all_up and make local_db_init
  • Path B full nuke: make local_nuke_rebuild_run (see Path B section above)

For a clean restart (no existing DB or Valkey data), run make local_clean (or make local_down_volumes) before starting again.

To remove local .env files and recreate them from templates (e.g. to test a clean env setup), run make local_env_remove (type Y when prompted), then make env_setup.

Reference

  • Env templates: infra/config/env-templates/. Local overrides (gitignored): infra/config/local/. To remove all local .env files: make local_env_remove (prompts for Y).
  • Single README: Only the root README.md is named README; other docs use full-path names (e.g. INFRA.md, INFRA-DOCKER-LOCAL.md).