Nextgen Reports Desktop opens Studio in a dedicated application window with its own local engine. It includes the same designer, Preview, Library, JSON/object workflow, PDF/HTML/image/Office exports and local English documentation. Installer targets are Linux AppImage, Windows x64 NSIS and macOS DMG/ZIP (Apple Silicon and Intel build configurations). Linux interface checks run on the user's Linux iMac. Windows execution and macOS GUI execution remain unverified. macOS automatic installation remains disabled until a Developer ID signed release is available.
Install a release
Download the package for your platform from the published release links. Release
files live in a dedicated private GCS bucket in DME production and are streamed
through https://dmeclinic.com/downloads/nextgen-reports/stable/<runtime>/.
The gateway never receives your reports and does not cache installers on the
production server's disk.
- Linux x64: make the AppImage executable and open it. FUSE is normally required;
./Nextgen-Reports-VERSION-linux-x86_64.AppImage --appimage-extract-and-runworks without a FUSE mount. Keep the AppImage in a folder you can write for updates. A supported Chromium sandbox is required; see Linux sandbox setup below. - Windows x64: run the
.exeinstaller, select the destination and launch Nextgen Reports. It installs for the current user. Preserve the profile during uninstall if you want to keep Library and recovery data. Builds are not yet Authenticode signed, so Windows may show an unknown-publisher warning. - macOS: open the
.dmg, drag Nextgen Reports to Applications and open it. Choosearm64for Apple Silicon andx64for Intel. Current builds lack a Developer ID signature/notarization; Gatekeeper acceptance and automatic update installation are not established. Do not treat an unsigned test build as a signed distribution. The ZIP is also used by the signed update mechanism.
Software updates
The installed app checks the stable channel shortly after startup without interrupting your work. Help → Check for updates… shows the available version. Choose Download, then Restart and install when ready, or Later to keep working. Download does not install on ordinary quit. Before installation, the app captures the recovery draft and stops its own engine; a failed capture prevents installation. Reopen and restore the draft, then generate Preview. Library and saved projects stay in the profile. The updater checks the package SHA-512 from the HTTPS channel; downgrades and prereleases are disabled. Network/checksum errors leave the current installation in place and can be retried from Help.
Automatic installation applies to Linux AppImage and Windows installed NSIS builds.
The unpacked development folder reports that updates are unavailable. macOS update
code is present but disabled in unsigned builds; publishing an unsigned build does
not replace the signed latest-mac.yml channel. Native macOS signing/notarization
credentials must be configured before enabling that channel.
Open the application
After building/installing this checkout, double-click Nextgen Reports Desktop on the desktop. The existing Nextgen Reports Demo launcher also has a right-click Open desktop Studio action. The demo/documentation actions still open normal Chrome; the desktop action opens the separate application.
Expected startup: a short Starting the local report engine… screen, followed by Studio and a calculated sample report. Select Preview if Design is active. A second launch focuses the existing window for the same user-data directory. The app chooses a free loopback port; it does not take port 5274 or reuse the browser demo's engine or Library.
First desktop report
- Open File → Open project… (Ctrl+O on Linux) and choose a
.nrproject.jsonfile. The project is validated before replacing the workspace. Templates and raw JSON can also be opened through Studio's existing file controls. - Change a parameter or edit the design/data, then Generate preview.
- Use File → Save project as… (Ctrl+Shift+S) for a native save dialog. This saves the portable template/data/parameter bundle, not just the PDF. The file must be at most 8 MB. Invalid draft JSON cannot be saved as a valid project.
- Use Export PDF, Export Office, Export images or Export HTML. A native save dialog selects the destination. Cancel leaves the destination unchanged. Studio's Save project button also downloads a portable project.
- To retain versions inside this app, use Library → Save new copy / Save new version. Close and reopen the desktop app; the Library project remains. A separate recovery draft also retains the current workspace between launches; see the recovery workflow below.
- Help → Developer guide & code examples opens the English code guide in a separate application window. User manual and Desktop guide are available from the same menu. Local documentation works without an Internet connection.
Recover your workspace
The desktop app checks for changes every three seconds while the workspace is idle. A private recovery file stores the exact template/data editor text, filename and applied parameter controls, including unfinished JSON and blank values. Open Studio dialogs, active generation and exports pause capture; complete those operations first. Unapplied modal edits, undo history, selection, zoom, navigation, Library identity and generated preview pages are not included.
- Edit the report, data or parameters. The disabled status line in File shows the last successful draft save time. Save recovery draft now saves immediately.
- Close Studio normally, or reopen it after an unexpected interruption.
- Choose Restore draft to resume, Discard draft to start with the sample, or Quit to leave the draft untouched. A restored workspace says Recovered draft and has no active preview or export snapshot.
- Fix unfinished JSON if necessary, then Generate preview. Recovery never executes the restored report's scripts or refreshes external sources itself.
- File → Delete recovery draft… removes only the recovery file after confirmation. The open workspace stays unchanged; a subsequent edit creates a new draft. Closing without new edits does not recreate a deleted draft.
Closing: File → Close Studio or the main window's close button asks for confirmation, then attempts a final capture. If capture fails, Keep working lets you save or fix the problem; Close without latest draft retains only the last successful snapshot. Normal close stops the owned engine and auxiliary windows. An unexpected termination can lose edits since the last successful capture (normally up to three seconds when idle).
Opening a project or creating a new report asks before replacing the workspace in desktop mode. The recovery file follows the current workspace; it is not a multi-project history. Save a project file or Library version before switching. The draft can contain the report's entire data and is not encrypted: it is a current-user-only local file, not a substitute for backups. Maximum workspace snapshot size is 16 MB. Oversized or failed writes retain the previous snapshot. An unreadable recovery file is left untouched and automatic saving is paused; back up/remove that file while Studio is closed, then restart.
Build installers
Install .NET SDK 10, Node.js 22.12+, npm and Python 3 on the build host. Run:
npm ci --ignore-scripts
npm ci --prefix desktop --ignore-scripts
node scripts/package-desktop.mjsThis produces native packages and update metadata under
artifacts/installers/<runtime>, with a self-contained engine. Use a Mac for DMG
and ZIP, Windows for a native NSIS build, or Linux for AppImage. Linux can also
cross-build Windows with --platform=win32 --arch=x64; that does not verify Windows
execution. --arch=x64 on a Mac builds the Intel target; use --arch=arm64 for
Apple Silicon. GitHub Actions has native build jobs for all four targets.
The release version is desktop/package.json; commit its matching lockfile.
Set CSC_LINK and CSC_KEY_PASSWORD in the signing environment for macOS; do not
put signing material in the repository. Signing/notarization is a separate release
prerequisite, not supplied by the build scripts.
Publish a completed directory with python3 scripts/publish-desktop.py artifacts/installers/linux-x64 (or the other runtime). The publisher uploads
versioned binaries first, verifies their complete public bytes, then updates the
channel metadata. See release hosting for deployment and
rollback. No credentials are bundled into the app.
Build an unpacked Linux development folder
Build tools: .NET SDK 10, Node.js 22.12+ and npm, Python 3, and a Linux x64 desktop session. From the repository root:
npm ci --ignore-scripts
npm run prepare-editor
npm ci --prefix desktop --ignore-scripts
node scripts/build-desktop.mjs
python3 scripts/install-demo-launcher.py
bash scripts/open-desktop.shThe build script downloads the pinned Electron runtime explicitly, publishes a
self-contained .NET server, copies the app/local guides and writes an unpacked
application to artifacts/desktop/linux-x64. This folder is ignored by Git.
The built application does not need a separate .NET or Node installation to run.
First build needs network access to package feeds; normal report generation and
local documentation do not. Explicit external data-source refresh can use the
network, according to your configured source catalog.
Close the desktop app before rebuilding. The builder rejects a distribution with running processes. It stages a new build before replacing the previous directory. No OS service, automatic login startup or automatic update service is installed. The launchers refer to this checkout; reinstall them if it moves.
Linux sandbox setup
The renderer runs with sandboxing and context isolation enabled, without Node
integration or a filesystem/IPC bridge. On this iMac, the builder reuses the
existing root-owned setuid helper at /opt/google/chrome/chrome-sandbox through
a symlink; it keeps Electron's original helper as chrome-sandbox.bundled.
This does not launch Chrome or disable the sandbox, and does not modify the
system helper. Chromium/Electron and this helper combination was launch-tested
on this host.
Installed AppImages also reuse a valid root-owned Chrome helper when available. Otherwise the host must permit Chromium user-namespace sandboxing.
When moving the folder to another Linux machine, ensure a supported sandbox
configuration is available there. The helper symlink requires the same system
path; an administrator may instead configure the bundled helper according to
that system's Electron installation policy. No cross-machine portability or
system package installation is claimed. Do not use --no-sandbox as a workaround.
The directory is a local unpacked build, not a signed DEB/RPM/AppImage installer.
Where files live
Default application profile: ~/.config/NextgenReportsDesktop on Linux,
~/Library/Application Support/NextgenReportsDesktop on macOS and
%APPDATA%\NextgenReportsDesktop on Windows. Help → About
shows the actual path. It contains:
| Location | Contents |
|---|---|
| reports/library.db | Desktop Library and project versions |
| reports/schedules.db | Schedule metadata; local desktop mode does not run an authenticated server UI |
| reports/keys | Data-protection keys, restricted to the current user |
| workspace-recovery.json | Last workspace draft, including template/data text and parameters; current-user read/write only |
| studio.log | Current startup/engine log, bounded to 2 MB and reset each launch |
| Other profile files | Electron's local browser state/cache |
Exports and portable projects go to the location you choose. Back up reports and workspace-recovery.json
while the application is closed. Deleting the application folder does not remove
its profile. Deleting the profile removes saved Library data; preserve a backup
or portable projects first.
Advanced hosts may choose an isolated profile with NEXTGEN_DESKTOP_USER_DATA.
The engine uses NEXTGEN_STATE_DIRECTORY internally for state/key storage.
Desktop startup overrides inherited server-account and Library/schedule file
settings so it cannot accidentally reuse a separate Studio server's identity
or database paths. It can use explicitly configured NEXTGEN_DATA_SOURCES and
NEXTGEN_HTTP_SOURCES catalogs; see data sources.
Trusted report scripts
Scripts are disabled by default. To enable the existing TypeScript pipeline for your trusted local templates, close the app and start it explicitly with:
NEXTGEN_DESKTOP_SCRIPTS=1 bash scripts/open-desktop.shThe compiler uses Electron's bundled Node runtime in a child process; no separate Node installation is needed by the built app. Help → About shows whether scripts were enabled. Script validation, limits and trust boundaries remain those in the event guide. This is not an offline mobile runtime or an untrusted-report sandbox.
Engine ownership and troubleshooting
Each desktop instance owns a fresh loopback server and a random, memory-only capability. Only its Electron session adds that capability to requests. Opening the displayed engine URL in an unrelated browser or sending an ordinary curl request returns 403; use the desktop window. This is separate from the regular Studio URL at 5274. Cross-origin navigation is not embedded; supported external links ask before opening the default application.
| Symptom | What to do |
|---|---|
| Desktop build is missing | Run the build command before using the launcher |
| Sandbox startup failure | Check the Linux sandbox setup above; keep sandboxing enabled |
| Engine startup error | Read the path shown in the error dialog and studio.log |
| Unexpected engine exit | Close/reopen the app and restore the draft or a saved project/Library version |
| Cannot open/save a project | Check file permissions, valid project JSON and the 8 MB limit |
| Missing recent edits after restart | Check the File draft status; capture pauses during modal dialogs, generation and export |
Normal close stops the engine through its stdin lifetime pipe, with termination fallbacks if it cannot stop. If the parent process dies, pipe EOF also requests engine shutdown. The app never terminates unrelated Studio/demo processes. Windows/macOS GUI verification, Developer ID/Authenticode signing, notarization, file associations and autonomous background scheduling remain separate release work.
Security setup follows the Electron security guide and single-instance lifecycle API.