Local Development

Set up dependencies, start the Core-first stack, work with the development mailbox, and run quality and smoke checks.

Prerequisites

This page assumes you already have a maintainer-reviewed source copy. Acquisition links are withheld. Don't restore configuration from historical environment files or database backups. Run all commands at the source root.

You'll need Node.js 20+, Corepack, locked pnpm 9.7.0, Docker Engine, and Compose 2.24.4+. The development overlay uses !override, so older Compose versions may not parse it correctly. Before going further, check node --version, corepack pnpm --version, docker info, and docker compose version.

Prepare and start

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

setup creates a protected .state/core-dev.env and installs frozen dependencies. config validates the merged Compose model and prints the service names. The fixed Compose project is mywebdrive-core-dev, with the entry point at http://127.0.0.1:8080. Running another checkout that uses the same project name can cause conflicts—concurrent copies aren't isolated test environments.

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

Development mailbox limitation

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

Because of this, a successful default start doesn't 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 the type, permissions, and preservation requirements first. reset isn't 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 afterward. pnpm run test:docs and pnpm run verify:docs check documentation/OpenAPI authority; they don't 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—don't rewrite those on macOS. legacy:help and legacy:status are observation-only; other legacy commands exit 64. Split-service migration loops aren't the current workflow.