Build and verify

Build artifacts independently and apply database migrations as a separate step. Use the pinned versions and preserve existing data when updating a local installation.

Application checks

pnpm check
pnpm build
pnpm test
pnpm test:integration
pnpm exec playwright install chromium
pnpm test:e2e
pnpm audit
git diff --check

Integration tests use disposable PostgreSQL instances. Application browser tests use a separate Compose project with their own Keycloak and Mailpit. Stop a regular Next.js development server before running development-mode browser tests, or use the compiled test mode documented in the repository.

After pnpm build, AUTH_TEST_BUILD=true pnpm test:e2e tests the compiled API, worker and panel. Do not rebuild shared packages while development-mode tests are running: their file watcher restarts the API. Release integration tests include real database shutdown, two durable nodes, rollback, restricted-role access and backup recovery.

Validate the independent image and production TLS/mTLS boundary with disposable certificates and containers:

docker build -f apps/distribution/Dockerfile -t localisync-distribution-primary .
pnpm test:delivery:tls

This test rejects absent/untrusted client certificates, wrong control credentials and internal routes on the public listener. It uses no application credentials and cleans up only its own temporary containers. It does not provision production hosts or certificates.

pnpm test:e2e runs functional tests first, then starts fresh API/panel processes for the tagged load measurements. This keeps benchmark traffic from consuming the functional suite’s request-limit window. Both groups retain the normal API limits and neither group is skipped.

Documentation checks

pnpm docs:check
pnpm test:docs

The documentation checks validate contracts, generate the static reference, check internal links and test search/navigation against built output. They do not require application services or SMTP.

When adding a feature, update its guide and API contract in the same change. Internal-only refactors should record that public documentation behavior is unchanged.

Run compiled application builds

After building, run each process in its own terminal:

pnpm --filter @localisync/api start
pnpm start

The API and panel also have separate Dockerfiles. The API Dockerfile’s migration target applies migrations explicitly. Runtime database credentials must remain distinct from the migration owner.

Serve static documentation

pnpm build:docs produces apps/docs/dist. It contains HTML, local assets, the search index and downloadable OpenAPI files. Serve it from a static web server with directory-index routing and its generated 404 page.

Build and run the independent documentation image locally:

docker build -f apps/docs/Dockerfile -t localisync-docs:local .
docker run --rm -p 127.0.0.1:4323:8080 localisync-docs:local

The default image points to the normal local panel and uses the local documentation canonical origin. When building for another environment, set the public DOCS_SITE_URL and DOCS_PANEL_URL build arguments to verified origins. The image contains no application credentials and serves on an unprivileged port.

Update and recover

Apply new migrations with pnpm db:migrate before running application code that needs them. Keep existing .env and persistent database volumes. Reverting application code does not require dropping additive tables or audit records.

Keep each documentation deployment’s HTML, assets and search index together. Publish complete build artifacts; retain old hashed assets long enough for already-open pages. Production application TLS, backup/restore and proxy configuration remain separate deployment work.