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>
This commit is contained in:
parent
071b2a5644
commit
bd225d9e3a
22 changed files with 1367 additions and 17 deletions
72
docs/install.md
Normal file
72
docs/install.md
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
# 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 |
|
||||
Loading…
Add table
Add a link
Reference in a new issue