Lutra/docs/install.md
danny bd225d9e3a B1: alpha installers (NSIS, DMG), identifier com.tyrveil.lutra with data migration
- App identifier com.tyrveil.lutra (D26) in tauri.conf.json and
  rendezvous::APP_IDENTIFIER; a test keeps them equal.
- First normal start copies settings.json, recovery/ and tools/ once from
  the dev.lutra.desktop directories (staging dir + rename, logged, info
  notification); old directories stay untouched.
- Bundling on: per-user NSIS setup (English, German, Start menu, optional
  desktop shortcut, uninstaller) and DMG; `cargo xtask bundle` builds the
  platform's installer, joining the DMG backgrounds into a HiDPI TIFF on
  macOS. build.rs also writes icons/512x512.png for the .icns.
- Installer images from the banner, designed by Amy, generated by
  `cargo xtask installer-images` (assets/installer/, ASSETS.md rows);
  approved by Daniel.
- docs/install.md (SmartScreen, Gatekeeper, uninstall, data locations),
  README install section, architecture, development and macOS notes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 21:48:15 +01:00

72 lines
4.6 KiB
Markdown

# Installing Lutra
> **Status:** draft, alpha installers · **Last updated:** 2026-10-31
Lutra's alpha comes as an installer for Windows (a setup `.exe`) and macOS (a `.dmg`). Both are **not signed yet**, so Windows and macOS warn before the first start; the steps below get past that once. Linux has no installer yet: build it from source ([`development.md`](development.md)).
The installers contain the desktop app only. The `lutra` command-line tool (`lutra .`, `lutra mcp`) is not in them yet; build it with `cargo build --release -p lutra-cli` if you need it.
## Building an installer
On the platform you want the installer for:
```sh
cargo xtask bundle
```
It builds the release app with the bundled UI and prints the installer's path and size: `target/release/bundle/nsis/Lutra_<version>_x64-setup.exe` on Windows, `target/release/bundle/dmg/Lutra_<version>_aarch64.dmg` on macOS. It needs the Tauri CLI (`cargo install tauri-cli --locked`) and, on macOS, the Xcode Command Line Tools ([`macos.md`](macos.md)).
## Windows
Lutra installs for your user only: no administrator rights, no UAC prompt. It needs Microsoft Edge WebView2, which Windows 10 and 11 already have; if it is missing, the setup downloads it.
1. Start `Lutra_<version>_x64-setup.exe`.
2. Windows SmartScreen says "Windows protected your PC", because the setup is not signed. Click **More info**, check that the app is `Lutra_<version>_x64-setup.exe` and the publisher is "Unknown publisher", then click **Run anyway**. If you downloaded the file with a browser, the browser may ask first whether to keep it.
3. The setup runs in English or German, following Windows. Click **Next**, keep or change the folder (default `%LOCALAPPDATA%\Lutra`), click **Install**.
4. On the last page, tick **Create desktop shortcut** if you want one, and click **Finish**.
Lutra is now in the Start menu as **Lutra**. Installing a newer setup over it updates it in place and keeps your settings.
For scripts: `Lutra_<version>_x64-setup.exe /S` installs silently with both shortcuts, `/D=C:\path` (last argument) picks the folder, `/NS` skips the shortcuts.
### Uninstalling on Windows
Settings → Apps → Installed apps → **Lutra** → … → **Uninstall**, or run `uninstall.exe` in the install folder. The uninstaller removes the app and its shortcuts. Your settings, recovery journal and Phpactor stay unless you tick **Delete the application data**.
## macOS
The DMG holds the app for Apple Silicon (M1 or newer), macOS 11 or newer.
1. Open `Lutra_<version>_aarch64.dmg` and drag **Lutra** onto **Applications**. Eject the DMG.
2. The first start is blocked because the app is not signed or notarised. In **Applications**, **right-click** (or Control-click) Lutra → **Open**, and click **Open** in the dialog. On macOS 15 Sequoia and newer that dialog has no Open button: click **Done**, then open **System Settings → Privacy & Security**, scroll to "Lutra was blocked", click **Open Anyway** and confirm with your password.
3. Alternatively, remove the quarantine flag once in Terminal and start Lutra normally:
```sh
xattr -dr com.apple.quarantine /Applications/Lutra.app
```
You need to do this once per installed version.
### Uninstalling on macOS
Quit Lutra and drag **Lutra** from **Applications** to the Trash. Your data stays; delete the folders below to remove it.
## Where your data lives
| What | Windows | macOS |
|---|---|---|
| The app | `%LOCALAPPDATA%\Lutra\` | `/Applications/Lutra.app` |
| Settings (`settings.json`), recovery journal (`recovery\`), downloaded Phpactor (`tools\`) | `%APPDATA%\com.tyrveil.lutra\` | `~/Library/Application Support/com.tyrveil.lutra/` |
| Window data of the web view (recent projects, layout) | `%LOCALAPPDATA%\com.tyrveil.lutra\` | `~/Library/WebKit/com.tyrveil.lutra/`, `~/Library/Caches/com.tyrveil.lutra/` |
On Linux, when built from source: settings in `~/.config/com.tyrveil.lutra/`, journal and tools in `~/.local/share/com.tyrveil.lutra/`.
**From a build before the installers.** Earlier builds used the identifier `dev.lutra.desktop`. The first start of a new build copies `settings.json`, the recovery journal and the downloaded Phpactor from the old `dev.lutra.desktop` folders once and shows a notification; the old folders stay untouched and can be deleted afterwards. Recent projects and the window layout are not copied.
An instance started with `--control PORT` or `--data-dir DIR` keeps its files in its own folder (see [`development.md`](development.md#data-directories)).
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-10-31 | major | B1: initial version, NSIS setup and DMG, unsigned |