Local Development

Prepare dependencies and protected state, start Core-first services and distinguish checks from runtime acceptance.

Prerequisites

This page is for developers who already hold a maintainer-reviewed source copy. Acquisition links remain withheld. Do not restore configuration from historical environment files or database backups. Run commands at the source root.

Use Node.js 20+, Corepack, locked pnpm 9.7.0, Docker Engine and Compose 2.24.4+. The development overlay uses !override; older Compose versions cannot be assumed to parse it correctly. Check node --version, corepack pnpm --version, docker info and docker compose version first.

Prepare and start

./manage-services.sh setup
./manage-services.sh config
./manage-services.sh start
./manage-services.sh status

setup prepares protected .state/core-dev.env and installs frozen dependencies. config validates the merged model and prints service names. The fixed Compose project is mywebdrive-core-dev, with entry point http://127.0.0.1:8080. Another checkout using the same project name can conflict; concurrent copies are not isolated test environments.

The stack includes database, Redis, object storage, migration, Core, Analytics Worker, mail adapter, Storage API/Worker, Prometheus, Web and Nginx. Only the entry point and development mail port are exposed to the host. Starting only the frontend does not make the file workflow functional.

Development mailbox limitation

The overlay replaces delivery with fake-email on local port 8025; it does not send real email. /v1/test/mailboxes/latest requires configured FAKE_EMAIL_TEST_TOKEN, a recipient and X-Test-Mailbox-Token. The default development overlay does not configure this test-read token. Port 8025 is not a ready-to-use inbox web page.

Consequently, a successful default start does not prove sign-in works end to end. For authentication tests use the repository's isolated smoke/browser configuration, or have the maintainer configure the private test-mailbox contract. Never expose the fake mailbox publicly, reuse its token in production or infer codes from the database.

Daily commands

| Command | Effect | | --- | --- | | ./manage-services.sh logs core-api | Last 200 log lines for a validated service | | ./manage-services.sh logs | Recent stack logs | | ./manage-services.sh stop | Stop containers, keeping volumes and secrets | | ./manage-services.sh config | Validate configuration without printing the full secret-bearing model | | ./manage-services.sh reset --confirm | Remove local containers and volumes, retaining the state file; use only for disposable data |

The manager refuses to overwrite unexpected state files. Check type, permissions and preservation requirements first. reset is not a normal restart.

Verification

./manage-services.sh quality
./manage-services.sh smoke

quality checks active builds, types, lint, tests, generated artifacts and documentation contracts without starting containers. smoke builds an isolated stack, uses disposable volumes and cleans up. pnpm run test:docs and pnpm run verify:docs check documentation/OpenAPI authority; they do not replace email receipt and a file round trip.

Browser smoke should cover sign-in, finalization, downloaded contents, administrative permission and desktop/mobile states. Linux is authoritative for upstream visual baselines; do not rewrite those on macOS. legacy:help and legacy:status are observation-only; other legacy commands exit 64. Split-service migration loops are not the current workflow.