A configurable C++ shell that turns an HTTPS website into a focused Linux, macOS, and Windows desktop application. It uses the operating system's native web engine through CHOC, preserves cookies and local storage, displays a branded offline page, disables the browser context menu, and prevents top-level navigation outside configured origins.
Without overrides, the repository builds:
Name: getBible.Life
Application URL: https://app.getbible.life/
Homepage: https://app.getbible.life/
Support URL: https://app.getbible.life/
Allowed origin: https://app.getbible.life
Application ID: live.getbible.app
Executable: getbible-life
Snap name: getbible-life
The default floating three-dot menu is disabled so it cannot cover controls owned by the website.
- Configurable name, domain, allowed origins, version, descriptions, support information, offline messages, window size, icons, and Store identities.
- JSON configuration with repository variable and secret overrides.
- Persistent native WebView cookies, local storage, and login state.
- Branded embedded offline, About, and Support pages.
- Top-level navigation restricted to configured HTTPS origins.
- Right-click, middle-click, auxiliary buttons, and keyboard context menus disabled.
- JavaScript and user-agent application detection for website-specific layouts.
- Linux portable archive and Snap packaging.
- Windows MSIX packaging with optional certificate signing.
- macOS DMG packaging with optional Developer ID signing and notarization.
- Automatic builds on every push to
main. - Tag-driven GitHub Releases with all packages and SHA-256 checksums.
- Optional Snap Store publication after the GitHub Release succeeds.
config/app.json Default application configuration
config/app.schema.json Configuration schema
branding/ Default and custom source icons
src/ C++ desktop shell
scripts/ Local build and packaging commands
tools/ Configuration and metadata generator
tests/ Generator tests
docs/ Integration and distribution guides
.github/workflows/build.yml Main-branch multi-platform builds
.github/workflows/release.yml Tag-driven release and Snap publication
Generated metadata is written under generated/ and should not be edited manually.
sudo apt update
sudo apt install --yes \
build-essential cmake git libgtk-3-dev libwebkit2gtk-4.1-dev \
pkg-config python3 python3-pil
chmod +x scripts/*.sh
./scripts/build-linux.sh
./build/getbible-lifeThe bootstrap script fetches the pinned upstream CHOC revision. Register it as a normal Git submodule in a local clone when desired:
./scripts/register-submodule.sh
git commit -m 'Register upstream CHOC submodule'Run on macOS with Xcode Command Line Tools, CMake, Git, Python 3, and Pillow:
chmod +x scripts/*.sh
./scripts/build-macos.sh
open ./build-macos/getbible-life.app
./scripts/package-macos.shSee macOS distribution.
Run from PowerShell on Windows with Visual Studio 2022 C++ tools, CMake, Git, Python 3, Pillow, and the Windows SDK:
python -m pip install --requirement tools/requirements.txt
./scripts/build-windows.ps1
./scripts/package-windows.ps1See Windows distribution.
Copy the default configuration and supply another icon:
mkdir -p config/sites branding/sites
cp config/app.json config/sites/example.json
cp /path/to/example.png branding/sites/example.pngMinimal profile:
{
"app": {
"name": "Example Portal",
"slug": "example-portal",
"id": "com.example.portal",
"version": "1.0.0",
"url": "https://portal.example.com/",
"homepage_url": "https://portal.example.com/",
"allowed_origins": ["https://portal.example.com"]
},
"window": {
"show_app_menu": false
},
"branding": {
"icon": "branding/sites/example.png"
},
"snap": {
"name": "example-portal"
},
"windows": {
"identity_name": "com.example.portal",
"publisher": "CN=Example Publisher",
"publisher_display_name": "Example Publisher"
}
}Build it:
WEBAPP_CONFIG_FILE=config/sites/example.json ./scripts/build-linux.shSee configuration.
Every page receives:
window.WebAppDesktopThe default profile also exposes:
window.GetBibleAppExample:
if (window.WebAppDesktop?.isApp) {
document.querySelector('.browser-only')?.remove();
}The document root receives webapp-desktop-app and a configurable application-specific class. Linux also appends GetBibleLifeDesktop/<version> to WebKitGTK's normal user agent. These markers control presentation only; they are not authentication credentials.
See website integration.
The embedded overlay menu is disabled by default. A website can add controls where they fit its own layout:
document.querySelector('#desktop-about')?.addEventListener('click', () => {
window.location.assign(window.WebAppDesktop.aboutURL);
});
document.querySelector('#desktop-support')?.addEventListener('click', () => {
window.location.assign(window.WebAppDesktop.supportURL);
});The internal destinations are webapp://app/about and webapp://app/support.
Every push to main runs Build all desktop targets and produces downloadable workflow artifacts for:
- Linux
.tar.gz; - Linux
.snap; - Windows
.msix; - macOS
.dmg.
Repository configuration and signing values are optional. The default GetBible profile is used when none are supplied.
After the main-branch checks pass, push a semantic version tag:
git checkout main
git pull --ff-only
git tag -s v1.0.0 -m 'getBible.Life 1.0.0'
git push origin v1.0.0Build and publish release then:
- builds all four packages;
- creates
SHA256SUMS; - creates the GitHub Release and uploads all packages;
- attempts Snap Store publication only afterward.
When SNAPCRAFT_STORE_CREDENTIALS is absent, the final Store job fails clearly, but the GitHub Release and downloadable packages remain available.
See automated releases and Snap Store distribution.
chmod +x scripts/*.sh
./scripts/validate.sh- Linux: GitHub Release archive or Snap Store.
- Windows: signed MSIX and Microsoft Store.
- macOS: signed/notarized DMG or a separately prepared Mac App Store submission.
The Snap Store distributes Linux packages only.
The template is GPL-3.0-or-later. CHOC is distributed separately under its ISC license.