{"id":17263824,"url":"https://github.com/holochain/kangaroo-electron","last_synced_at":"2025-07-30T04:33:04.590Z","repository":{"id":192947777,"uuid":"687788843","full_name":"holochain/kangaroo-electron","owner":"holochain","description":"Bundle your holochain app a a standalone electron app with a built-in conductor","archived":false,"fork":false,"pushed_at":"2025-07-22T13:56:18.000Z","size":3460,"stargazers_count":8,"open_issues_count":17,"forks_count":9,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-07-22T15:40:44.064Z","etag":null,"topics":["electron","holochain"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/holochain.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-09-06T02:24:13.000Z","updated_at":"2025-07-22T13:56:21.000Z","dependencies_parsed_at":"2024-12-21T01:19:02.340Z","dependency_job_id":"85a157d9-c94c-45c2-b7bf-ff8bc2246af5","html_url":"https://github.com/holochain/kangaroo-electron","commit_stats":null,"previous_names":["mattyg/holochain-kangaroo-electron","holochain/kangaroo-electron"],"tags_count":17,"template":true,"template_full_name":null,"purl":"pkg:github/holochain/kangaroo-electron","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holochain%2Fkangaroo-electron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holochain%2Fkangaroo-electron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holochain%2Fkangaroo-electron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holochain%2Fkangaroo-electron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/holochain","download_url":"https://codeload.github.com/holochain/kangaroo-electron/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holochain%2Fkangaroo-electron/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267809640,"owners_count":24147511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["electron","holochain"],"created_at":"2024-10-15T07:57:40.245Z","updated_at":"2025-07-30T04:33:04.574Z","avatar_url":"https://github.com/holochain.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Holochain-Kangaroo Electron\n\nPut your Holochain App in this Kangaroo's electron pouch and let it run.\n\nThis repository let's you easily convert your Holochain app into a standalone, electron-based cross-platform Desktop app.\n\n**Note:** Support for non-breaking updates to happ coordinator zomes is currently not built into the kangaroo.\n\n# Holochain Versions\n\nDepending on which Holochain minor version you want to use you should use the corresponding branch of this repository.\n\n\n- Holochain 0.4.x (stable): [main-0.4](https://github.com/holochain/kangaroo-electron/tree/main-0.4)\n- Holochain 0.5.x: [main](https://github.com/holochain/kangaroo-electron/tree/main)\n- Holochain 0.3.x: [main-0.3](https://github.com/holochain/kangaroo-electron/tree/main-0.3)\n\n# Instructions\n\n## Setup and Testing Locally\n\n1. Either use this repository as a template (by clicking on the green \"Use this template\" button) or fork it.\n   Using it as a template allows you to start with a clean git history and the contributors of this repository won't show up as contributors to your new repository. **Forking has the advantage of being able to relatively easily pull in updates from this parent repository at a later point in time.** If you fork it, it may be smart to work off a different branch than the main branch in your forked repository in order to be able to keep the main branch in sync with this parent repository and selectively merge into your working branch as needed.\n\n2. In the `kangaroo.config.ts` file, replace the `appId` and `productName` fields with names appropriate for your own app.\n\n3. In your local copy of the repository, run\n\n```\nyarn setup\n```\n\n4. Choose a version number in the `version` field of `kangaroo.config.ts`. And **Read** the section [Versioning](#Versioning) below to understand the implications.\n\n5. Paste the `.webhapp` file of your holochain app into the `pouch` folder.\n   **Note**: The kangaroo expects an `icon.png` of at least 256x256 pixel at the root level of your webhapp's UI assets.\n\n6. To test it, run\n\n```\nyarn dev\n```\n\n## Build the Distributable\n\n\u003e [!WARNING]\n\u003e The default bootstrap, signaling and ICE servers (used for connection establishment among peers)\n\u003e in `kangaroo.config.ts` have no availability guarantees whatsoever and are meant for testing\n\u003e purposes only.\n\u003e\n\u003e If you want to deploy your app to end-users, make sure to run your own\n\u003e instances of these servers or use servers that have guaranteed availability for the lifetime\n\u003e of your app's network(s).\n\u003e\n\u003e **Changing these URLs *after* deployment of your app can result in a network partition**.\n\n\n### Build locally\n\nTo build the app locally for your platform, run the build command for your respecive platform:\n\n```\nyarn build:linux\n\n# or\nyarn build:mac\n\n# or\nyarn build:windows\n```\n\n### Build on CI for all platforms\n\nThe general workflow goes as follows:\n\n1. Make sure that CI has access to your app's .webhapp file by either\n   - specifying the `webhapp` field in `kangaroo.config.ts` pointing to a URL where CI can fetch it and a sha256 to verify its integrity\n   - remove `pouch/*.webhapp` from the `.gitignore` file and commit your .webhapp to git.\n\n2. Create a draft release on github and set its \"Tag verion\" to the value of the `version` field that you chose in `kangaroo.config.ts` and prefix it with `v`, for example `v0.1.0`.\n\n3. Merge the main branch into the release branch and push it to github to trigger the release workflow.\n\nIf you do this for the first time you will need to create the `release` branch first:\n\n```\ngit checkout -b release\ngit merge main\ngit push --set-upstream origin release\n```\n\nFor subsequent releases after that you can run\n\n```\ngit checkout release\ngit merge main\ngit push\n```\n\n## Automatic Updates\n\nBy default, the kangaroo is set up to check github releases for semver compatible releases by their tag name whenever the app starts up and will prompt to install and restart if one is available. This can be disabled by setting `autoUpdates` to `false` in `kangaroo.config.ts`.\n\n\u003e [!NOTE]\n\u003e Note that once your app is deployed, this setting can only be turned on again for newer releases and users will have to manually install new versions.\n\n## Versioning\n\nTo allow for subsequent incompatible releases of your app (for example due to switching to a new Holochain version or introducing a breaking change in the integrity zomes of your .happ) without having to change the app's name or identifier, the kangaroo is set up to use semver to support incompatible versions of your app running fully independently from each other and store their data in dedicated locations on disk.\n\nExamples:\n\n- version 0.0.2 and 0.0.3 of your app will store their data in independent locations on disk and version 0.0.3 will not have access to any data created/obtained in version 0.0.2\n- version 0.3.4 will reuse the same Holochain conductor and data as version 0.3.2\n- versions 0.3.0-alpha and 0.3.0-beta will _not_ share data\n- versions 0.3.0-alpha.0 and 0.3.0-alpha.1 _will_ share data\n\n\u003e [!NOTE]\n\u003e It is your responsibility to make sure that if you mark two versions of your app as semver compatible they actually are compatible (e.g. that you don't try to run a new incompatible version of Holochain on existing databases).\n\n## Code Signing\n\n### macOS\n\nTo use code signing on macOS for your release in CI you will have to\n\n1. Set the `macOSCodeSigning` field to `true` in `kangaroo.config.ts`\n2. Add the following secrets to your github repository with the appropriate values:\n\n- `APPLE_DEV_IDENTITY`\n- `APPLE_ID_EMAIL`\n- `APPLE_ID_PASSWORD`\n- `APPLE_TEAM_ID`\n- `APPLE_CERTIFICATE`\n- `APPLE_CERTIFICATE_PASSWORD`\n\n3. Uncomment the line `afterSign: scripts/notarize.js` in `./templates/electron-builder-template.yml`.\n\n\u003e [!WARNING]\n\u003e **Unsigned applications are put under quarantine on macOS 15 (Sequoia).** The option in the Privacy \u0026 Security panel of the System Settings to allow them has been removed. To unset the quarantine attribute of an unsigned app,\nthe command `xattr -r -d com.apple.quarantine /path/to/app` can be executed from a Terminal. The app can then be run.\n\n### Windows\n\nIf you want to code sign your app with an EV certificate, you can follow [this guide](https://melatonin.dev/blog/how-to-code-sign-windows-installers-with-an-ev-cert-on-github-actions/) to get your EV certificate hosted on Azure Key Vault and then\n\n1. Set the `windowsEVCodeSigning` field to `true` in `kangaroo.config.ts`\n2. Add all the necessary secrets to the repository:\n\n- `AZURE_KEY_VAULT_URI`\n- `AZURE_CERT_NAME`\n- `AZURE_TENANT_ID`\n- `AZURE_CLIENT_ID`\n- `AZURE_CLIENT_SECRET`\n\n## Permissions on macOS\n\nAccess to things like camera and microphone on macOS require special permissions to be set in the .plist file. For this, uncomment the corresponding permissions in `./templates/electron-builder-template.yml` as needed.\n\n## Run your App from the command line\n\nIf you want to customize some runtime parameters you can run your app via the terminal and pass additional options:\n\n```\nOptions:\n  -V, --version                  output the version number\n  -p, --profile \u003cstring\u003e         Runs Holochain Kangaroo Electron (Test) with a custom profile with its own dedicated data store.\n  -n, --network-seed \u003cstring\u003e    If this is the first time running kangaroo with the given profile, this installs the happ with the\n                                 provided network seed.\n  --holochain-path \u003cpath\u003e        Runs Holochain Kangaroo Electron (Test) with the holochain binary at the provided path. Use with caution\n                                 since this may potentially corrupt your databases if the binary you use is not compatible with existing\n                                 databases.\n  --lair-path \u003cpath\u003e             Runs the Holochain Kangaroo Electron (Test) with the lair binary at the provided path. Use with caution\n                                 since this may potentially corrupt your databases if the binary you use is not compatible with existing\n                                 databases.\n  --holochain-rust-log \u003cstring\u003e  RUST_LOG value to pass to the holochain binary\n  --holochain-wasm-log \u003cstring\u003e  WASM_LOG value to pass to the holochain binary\n  --lair-rust-log \u003cstring\u003e       RUST_LOG value to pass to the lair keystore binary\n  -b, --bootstrap-url \u003curl\u003e      URL of the bootstrap server to use (not persisted across restarts).\n  -s, --signal-url \u003curl\u003e      URL of the signaling server to use (not persisted across restarts).\n  --ice-urls \u003cstring\u003e            Comma separated string of ICE server URLs to use. Is ignored if an external holochain binary is being used\n                                 (not persisted across restarts).\n  --print-holochain-logs         Print holochain logs directly to the terminal (they will be still written to the logfile as well)\n  -h, --help                     display help for command\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fholochain%2Fkangaroo-electron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fholochain%2Fkangaroo-electron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fholochain%2Fkangaroo-electron/lists"}