# IdeA Server/Client Remote Deployment

`idea --serve` serves the web UI and the API from the same origin. The frontend
build must be available as a web root containing `index.html`.

## Local Development

The web build **must** be produced with the `http` transport, otherwise the
served `dist/` is a desktop (Tauri) build that fails in a plain browser with
`window.__TAURI_INTERNALS__ is undefined`. The frontend uses **npm**, not pnpm:

```bash
cd frontend && VITE_TRANSPORT=http npx vite build && cd ..
idea --serve --web-root frontend/dist --app-data-dir "$HOME/.local/share/app.idea.ide"
```

The default local listener is `127.0.0.1:17373`. Loopback development may use
plain HTTP; the session cookie is still `HttpOnly` and `SameSite=Strict`.

### App data directory (must match the desktop app)

`idea --serve` reads/writes the same on-disk data as the desktop app
(projects, profiles, templates). It resolves the app-data directory in this
order:

1. `--app-data-dir PATH`
2. `IDEA_APP_DATA_DIR`
3. platform default for the Tauri identifier `app.idea.ide`
   (`$XDG_DATA_HOME/app.idea.ide`, else `$HOME/.local/share/app.idea.ide`)

The resolved path is printed at startup (`idea --serve: app data dir = …`).

> **Do not run the desktop app and `idea --serve` on the same app-data
> directory at the same time.** There is no inter-process lock yet, so two
> concurrent writers can corrupt state. Close the desktop app while serving.

## Packaged Artifact

The release artifact is still a single IdeA binary/AppImage. Packaging must copy
the frontend build output (`frontend/dist`) into the packaged `web/` resource
next to the binary. `idea --serve` resolves assets in this order:

1. `--web-root PATH`
2. `IDEA_WEB_ROOT`
3. packaged `web/`, then packaged `frontend/dist/`
4. development fallback `frontend/dist` relative to the current directory

If no `index.html` is found, the server refuses to start.

## Remote HTTPS

Public exposure requires a reverse proxy that terminates HTTPS:

```bash
idea --serve \
  --listen 127.0.0.1:17373 \
  --allow-remote \
  --public-origin https://idea.example.com \
  --trust-reverse-proxy
```

The proxy must forward the same origin for the SPA, `/api/*`, and `/api/ws`.
Do not expose the backend on a public non-loopback address without TLS proxying.
Secrets must never be placed in URLs; pairing uses `POST /api/pair` and then an
`HttpOnly`, `Secure`, `SameSite=Strict` session cookie.