tianma-if
aca0f17113
Replace the old E menu-bar mark with the cat brand template, and swap the unused sync/backup tray actions for an interactive screenshot that saves into a note.
126 lines
5.6 KiB
Markdown
126 lines
5.6 KiB
Markdown
# EdgeEver Desktop
|
|
|
|
The desktop application deliberately reuses the Web renderer from `apps/web`.
|
|
Electron owns the window and OS lifecycle; the Rust sidecar owns local SQLite
|
|
and native data services. The renderer never receives Node.js access.
|
|
|
|
Development prerequisites:
|
|
|
|
- Bun dependencies installed with `bun install`
|
|
- Rust toolchain (`cargo`) installed
|
|
- Web dev server available at `http://127.0.0.1:5173`
|
|
- Debug sidecar built at `crates/desktop-sidecar/target/debug/edgeever-sidecar`
|
|
|
|
Run the shell with:
|
|
|
|
```sh
|
|
bun run dev:desktop
|
|
```
|
|
|
|
The sidecar can be overridden for development with
|
|
`EDGE_EVER_SIDECAR_PATH=/absolute/path/to/edgeever-sidecar`.
|
|
|
|
## App icon (macOS Dock)
|
|
|
|
Dock tiles need a complete multi-resolution `.icns` (including 1024px). Do not
|
|
point electron-builder at a lone 512 PWA PNG — that produces a thin icon pack
|
|
and macOS can show a blank Dock placeholder forever after installs.
|
|
|
|
Regenerate committed icon assets after changing the brand mark:
|
|
|
|
```sh
|
|
bun run prepare:desktop:icons
|
|
```
|
|
|
|
This writes `apps/desktop/assets/icon.icns` (full ICNS), `icon.png` (1024
|
|
master), and the macOS menu-bar template icons from the brand mark.
|
|
Packaging validation rejects incomplete ICNS types. Runtime also calls
|
|
`app.dock.setIcon` as a Launch Services / Dock cache fallback.
|
|
|
|
Preview the committed icon at its real Dock size without starting EdgeEver:
|
|
|
|
```sh
|
|
bun run preview:desktop:icon
|
|
```
|
|
|
|
The temporary preview stays in the Dock until you quit it from the icon's
|
|
context menu.
|
|
|
|
Build an unsigned installer for the current platform with:
|
|
|
|
```sh
|
|
bun run prepare:desktop:icons
|
|
bun run build:web
|
|
bun run build:desktop:sidecar
|
|
CSC_IDENTITY_AUTO_DISCOVERY=false bun run --cwd apps/desktop dist -- --publish never
|
|
```
|
|
|
|
The resulting DMG, ZIP updater package, NSIS installer, or AppImage is written
|
|
under `release/desktop`. Formal macOS Releases contain separate `arm64` and
|
|
`x64` DMGs; each package includes a Rust sidecar compiled for the same
|
|
architecture. The CI workflow accepts optional signing secrets:
|
|
|
|
On macOS, users can double-click EdgeEver in the mounted DMG and choose
|
|
**Install and Launch**. The app moves itself to `Applications`, relaunches the
|
|
installed copy, and ejects any mounted EdgeEver installer images so macOS does
|
|
not retain duplicate file-association entries. Dragging the app to
|
|
`Applications` remains supported; launching the installed copy also performs
|
|
the installer-image cleanup.
|
|
|
|
- `EDGEEVER_MAC_CERTIFICATE_BASE64` and `EDGEEVER_MAC_CERTIFICATE_PASSWORD`
|
|
- `EDGEEVER_APPLE_ID`, `EDGEEVER_APPLE_APP_SPECIFIC_PASSWORD`, and `EDGEEVER_APPLE_TEAM_ID`
|
|
- `EDGEEVER_WINDOWS_CERTIFICATE_BASE64` and `EDGEEVER_WINDOWS_CERTIFICATE_PASSWORD`
|
|
|
|
When these secrets are absent, CI produces unsigned verification artifacts.
|
|
Private signing material is never committed to the repository.
|
|
|
|
The workflow keeps `workflow_dispatch` builds as non-publishing verification
|
|
runs. When a GitHub Release is published, the workflow first compares it with
|
|
the previous formal Release. It rebuilds and publishes the installer through
|
|
electron-builder only when Electron, the Rust sidecar, native dependencies,
|
|
packaging configuration, or desktop build tooling changed. Web-only Releases
|
|
reuse the previous verified macOS DMGs and updater metadata, Windows Preview
|
|
installer, and Linux Preview AppImage without renaming them, so native runners
|
|
and signing pipelines are not scheduled unnecessarily.
|
|
|
|
Formal Releases also contain a Linux x64 AppImage Preview built on Ubuntu
|
|
22.04. The workflow verifies the Electron and Rust ELF architectures, caps the
|
|
sidecar requirement at glibc 2.35, runs the packaged sidecar integration suite,
|
|
performs an Xvfb first-launch smoke test, and publishes a matching
|
|
`SHA256SUMS-linux.txt` and `latest-linux.yml`. Linux Preview releases must pass
|
|
a real AppImage-to-AppImage automatic update through the cross-version gate. See
|
|
[`docs/linux-preview.md`](../../docs/linux-preview.md).
|
|
|
|
The desktop Settings page exposes the sidecar's local backup list. Restoring a
|
|
backup creates an additional protective backup first, restores the SQLite
|
|
database in place, restores the staged offline attachment directory when the
|
|
snapshot contains one, applies any newer migrations, and reloads the workspace.
|
|
|
|
Packaged macOS builds also expose **Settings → Advanced → Clear local data**.
|
|
After an explicit destructive confirmation, EdgeEver stops the local sidecar,
|
|
removes every account's local SQLite data, unsynced queue, offline attachments,
|
|
caches, backups, settings, and sign-in state, then relaunches into first-run
|
|
setup. Server data and files exported outside the app data directory are never
|
|
removed by this action.
|
|
|
|
Local SQLite data, backups, staged attachments, and resource cache are scoped
|
|
by the configured instance and authenticated user. Existing pre-scope data is
|
|
migrated to the first authenticated account that opens the upgraded desktop
|
|
app.
|
|
|
|
On Unix-like systems the sidecar also enforces private permissions for its data
|
|
directory (0700) and SQLite/backup files (0600); Windows uses the platform's
|
|
user-data ACLs.
|
|
|
|
On startup the sidecar receives the repository `migrations/` directory and
|
|
applies unapplied SQL files into the per-user SQLite database. Migration files
|
|
are never copied into the user data directory or modified in place.
|
|
|
|
Main-process diagnostics are written to `userData/logs/desktop.log` and rotate
|
|
at 5 MiB, retaining one `.1` archive so long-running installations cannot grow
|
|
logs without bound.
|
|
|
|
If the sidecar exits unexpectedly, Electron records the exit and retries it
|
|
with exponential backoff (up to 30 seconds). Intentional shutdowns and account
|
|
or instance switches stop the process without scheduling a restart.
|