Zenius Desktop

Desktop wrapper for https://www.zenius.net/ built with Electron.

Overview

Zenius Desktop packages the Zenius web experience as a native desktop application for:

• GNU/Linux
• macOS
• Windows

The app loads the live Zenius site inside Electron, uses the Zenius icon set, removes the default Electron menu bar, and keeps platform packaging in one repository.

Download

Compiled binaries are published in GitHub Releases:

• Latest release: https://github.com/panggi/zenius-desktop/releases/latest
• All releases: https://github.com/panggi/zenius-desktop/releases

Download note:

• GNU/Linux and Windows releases are intended for normal download and install.
• macOS releases are published from GitHub Actions too, but if Apple signing secrets are not configured yet, the macOS build is unsigned and may require manual Gatekeeper override such as right-click -> Open.

Versioning

The application version has a single source of truth:

• package.json

Useful command:

npm run version:print

Build artifact names are generated from that same version through Electron Builder.

Requirements

• Node.js 20+
• npm 10+
• For the documented local build path, build AppImage on GNU/Linux, DMG on macOS, and NSIS on Windows.

Install

For day-to-day development:

npm install

For clean, reproducible builds on CI or a fresh working tree:

npm ci

Run locally

Standard local launch:

npm start

If your Linux environment requires Electron to run without the Chromium sandbox helper, use:

npm run start:no-sandbox

Build

electron-builder builds the current host platform by default. This repository does not use one local command to produce GNU/Linux, macOS, and Windows installers from a single machine.

Use these commands as the supported local build paths:

• GNU/Linux host: npm run build:linux
• macOS host: npm run build:mac
• Windows host: npm run build:win

If you need all release installers together, use the GitHub Actions workflow described below.

Build the configured installer for the current host platform:

npm run dist

Build an unpacked app directory for the current host platform:

npm run pack

GNU/Linux

Build the AppImage on a GNU/Linux machine:

npm run build:binary

or:

npm run build:linux

Expected output:

dist/Zenius-<version>-linux-<arch>.AppImage

Example:

dist/Zenius-0.1.1-linux-x86_64.AppImage

macOS

Build the DMG on a macOS machine:

npm run build:mac

Expected output:

dist/Zenius-<version>-mac-<arch>.dmg
dist/mac-<arch>/Zenius.app
dist/latest-mac.yml

Example on Apple Silicon:

dist/Zenius-0.1.1-mac-arm64.dmg
dist/mac-arm64/Zenius.app

macOS build behavior:

• Local builds without Apple signing credentials are ad-hoc signed.
• Ad-hoc signed builds can run locally after packaging, but Gatekeeper may reject them on another Mac until the user manually overrides it with right-click -> Open.
• Signed and notarized macOS release builds require Apple credentials in CI.
• The mac app bundle uses build/entitlements.mac.plist and build/entitlements.mac.inherit.plist during signing.

Windows

Build the NSIS installer on Windows:

npm run build:win

Expected output:

dist/Zenius-<version>-win-<arch>.exe

Example:

dist/Zenius-0.1.1-win-x64.exe

Test

Run the test suite:

npm test

Run the coverage gate:

npm run coverage

Coverage is enforced at:

• 100% statements
• 100% branches
• 100% functions
• 100% lines

Security behavior

The app applies a restrictive Electron security policy:

• Node integration is disabled for renderer content.
• Context isolation and renderer sandboxing are enabled.
• Webviews are blocked.
• Only trusted Zenius HTTPS origins stay inside the main app window.
• External links open in the system browser only for approved protocols.
• Electron permission requests are denied by default.

Google sign-in is supported with a narrow exception:

• accounts.google.com is allowed to stay inside the app for the OAuth flow.
• Other non-Zenius destinations still open in the system browser.

GitHub Actions

The repository includes a GitHub Actions workflow at:

• .github/workflows/build.yml

It does the following:

• reads the version from package.json
• runs tests and the coverage gate on Ubuntu
• builds GNU/Linux, macOS, and Windows installers on native runners
• uploads the generated installers as workflow artifacts
• publishes GNU/Linux, macOS, and Windows binaries to GitHub Releases on version tags

Platform build matrix:

• Ubuntu runner: npm run build:linux -> dist/*.AppImage
• macOS runner: npm run build:mac -> dist/*.dmg
• Windows runner: npm run build:win -> dist/*.exe

macOS signing and notarization:

• release macOS builds are always produced by the GitHub Actions macOS job
• if Apple signing secrets are configured, the macOS build is signed and notarized
• if Apple signing secrets are not configured, the macOS build is still published but is only ad-hoc signed and may require manual override on the user's Mac

How to avoid Gatekeeper warnings for macOS releases:

• do not ship unsigned macOS builds if you want normal double-click open behavior
• enroll in the Apple Developer Program and create a Developer ID Application certificate
• export that certificate as a .p12 file and store it in GitHub as CSC_LINK
• store the .p12 password in GitHub as CSC_KEY_PASSWORD
• create an App Store Connect API key and store it as APPLE_API_KEY, APPLE_API_KEY_ID, and APPLE_API_ISSUER
• publish a new version tag after those secrets are configured so the GitHub Actions macOS job can sign and notarize the DMG

What macOS users can do if the release is still unsigned:

• move the app to Applications
• try to open it once so Gatekeeper records the block
• open System Settings -> Privacy & Security
• click Open Anyway for Zenius
• if macOS still blocks it, right-click the app and choose Open

The proper fix is signing plus notarization. The Open Anyway flow is only a local override for users who trust the downloaded build.

Optional GitHub Secrets for signed/notarized macOS releases:

• CSC_LINK
• CSC_KEY_PASSWORD
• APPLE_API_KEY
• APPLE_API_KEY_ID
• APPLE_API_ISSUER

Release publishing rules:

• release assets are created only from GitHub Actions build outputs
• the Git tag must match the app version in package.json
• example: if package.json is 0.1.1, the release tag must be v0.1.1

Typical release flow:

git tag v$(npm run --silent version:print)
git push origin main --tags

The workflow runs on:

• pull requests
• pushes to main
• tags matching v*
• manual dispatch

Project structure

.
├── .github/workflows/build.yml
├── assets/
├── src/
│   ├── main.js
│   └── preload.js
├── test/
├── package.json
└── README.md

License

This project is licensed under the MIT License. See LICENSE.