Local setup

Run the current application on your development machine. This setup uses Keycloak development mode and loopback ports; production deployment is a separate task.

Requirements

• A local checkout of the Localisync repository.
• Node 24.16.0 and pnpm 11.5.0, as pinned by the repository.
• Docker with Docker Compose and a running daemon.
• Available panel/API/identity/database ports: 3010, 4010, 8081, 55435.
• A reachable SMTP service, or the optional development Mailpit below.

Run commands from the repository root. Use 127.0.0.1 consistently; mixing it with localhost changes origins and cookie scope.

1. Install and create local configuration

pnpm install --frozen-lockfile
pnpm db:generate
pnpm auth:env

auth:env creates an ignored .env with generated secrets and owner-only permissions. It refuses to overwrite an existing file. Keep existing configuration when updating an installation; do not generate new secrets against an existing database volume.

2. Configure mail

If you already have Mailpit or authenticated SMTP, reuse it with the SMTP settings. For a fresh local mailbox, use the optional Compose overlay in the next step and set these values in .env:

.env — optional local Mailpit

SMTP_HOST=mailpit
SMTP_PORT=1025
SMTP_FROM=no-reply@localisync.test
SMTP_SECURITY=none
SMTP_USERNAME=
SMTP_PASSWORD=
SMTP_ALLOW_INSECURE_LOCAL=true
SMTP_APP_HOST=127.0.0.1
SMTP_APP_PORT=1025

Keycloak reaches mailpit over the Compose network; the host API uses its loopback SMTP port. For a port conflict, set MAILPIT_HTTP_PORT / MAILPIT_SMTP_PORT in .env and match SMTP_APP_PORT to the latter. SMTP_PORT inside the network stays 1025.

3. Start infrastructure and apply migrations

With the optional mailbox:

docker compose -f compose.yaml -f compose.mailpit.yaml up -d postgres keycloak mailpit
pnpm db:migrate

If you reuse an existing mail service, start only the base infrastructure:

docker compose up -d postgres keycloak
pnpm db:migrate

Wait for PostgreSQL health and Keycloak startup before configuring authentication. The base Compose file keeps database data in its persistent volume. Migration is an explicit step; starting the API does not run migrations.

4. Configure identity and start the application

pnpm auth:configure
pnpm build:delivery
pnpm dev:api

In a second terminal at the repository root:

pnpm dev

Open the panel at http://127.0.0.1:3010. Keycloak uses port 8081; the API uses 4010. On Linux, the API bind address and backchannel URL must be reachable from the Keycloak container; see Configuration.

5. Invite the first account

With the optional local Mailpit configuration, the following illustrative address stays in the local mailbox:

pnpm auth:invite --email developer@localisync.test

Open Mailpit at http://127.0.0.1:8025 (or your configured HTTP port), follow the setup email, verify the address and set your password. Then follow the Quick start.

For real SMTP, substitute an address you control and intend to invite. See Operator invitations.

Run only the documentation

Documentation needs neither the .env above nor Docker services:

pnpm install --frozen-lockfile
pnpm dev:docs

Open http://127.0.0.1:4321. To test full-text search, build and preview the static output:

pnpm build:docs
pnpm preview:docs

Stop safely

Stop the API and panel terminal processes. Use docker compose stop for infrastructure, or the same two-file Compose invocation with stop when using optional Mailpit. Keep database volumes and .env together. Removing volumes is data deletion, not a troubleshooting step.

Enable file transfers

After application migrations, prepare the transfer worker and private storage. Run pnpm transfers:prepare and pnpm db:queue, then complete publishing configuration and start pnpm dev:worker in addition to the API and panel. The combined worker requires all three queues and its permanent release configuration. Transfer jobs remain queued until the separate worker is running.