lightningrodlabs / electron-holochain-template

This project is a template that can be used to start projects that utilize holochain as a backend and electron + web as a frontend. It does not make any assumptions about a front-end framework

Your Project Name Here

This template gives you only what you need to get up and running with a new project that uses electron and holochain!

Check out the video walkthrough, just note that some minor details may have changed since then, but it will still be super useful to understand how to utilize this template: https://www.youtube.com/watch?v=jFraPKl2rPk.

IMPORTANT! Check Dependency Versions Information (Holochain etc)

Table of Contents

• Set Up after Clone
  • App Icon Images
• Run Locally and Develop on your Computer
• Multi User Development Testing
• Building / Packaging
• Versioning for User Data
• IMPORTANT! Dependency Versions Information (Holochain etc)

Set Up after Clone

Global find and replace:

ElectronHolochainTemplate: replace with the actual name you wish to see appear in users desktop launcher icons: e.g. "Acorn"

com.some-domain-name.app-name: replace with an Apple "bundle Id" that is registered on your Apple Developer account

App Icon Images

Replace electron/build/icon.icns. This one is utilized by MacOS.

Replace electron/build/icon.ico. This one is utilized by Windows

TODO: linux

Run Locally and Develop on your Computer

Prerequisites

• Have rust language (stable) installed on your system
• Have nodejs version 16 installed on your system

Then run

• npm run install-deps
• npm run dev

In the future, just run npm run dev anytime to develop.

When you run npm run dev a user-data/ directory is created and this is where user data including private keys, and also data generated through use of the app is stored.

You can run npm run user-data-reset if you have user data in development, but you want to clear it, and start over with fresh identities.

NOTE: if you see a blank screen once electron launches the app, refresh the page (using View -> Reload or Cmd/Ctrl-R) to see app contents.

Commands that are more specific to your use case:

dna

• Have rust language (stable) installed on your system, then...
• npm run happ-install: installs wasm32 compilation target for rust as well as the Holochain CLI
• npm run happ-pack: compiles zomes into wasm and packages them into a .dna and a .happ using Holochain CLI
• npm run happ-reset: runs happ-pack and clears user data (Run this anytime you change the code in happ folder during development)

web (user interface)

• Use nodejs version 16
• npm run web-install
• npm run web

electron

• npm run electron-install
• npm run electron-tsc (needs to be re-run whenever electron folder source code changes)
• npm run electron

Multi-User Development Testing

Some features to develop and test require running two instances of the app simultaneously. The project is set up with that in mind.

run the following commands in separate terminal instances (must have a running instance of acorn for the first user, either by running npm run dev or the below commands without the 2):

• npm run web2
• npm run electron2

After running these commands, a user2-data/ directory is created with user data. It too can be cleared by running npm run user-data-reset.

Building / Packaging

To build:

• npm run build

The packaged executables can be found in electron/out.

In order to get cross-platform builds, just tag your repository like v0.0.1 and push those tags to Github. CI will automatically start running a build, under the "Release" action.

Macos: You will need to have set the following environment variables as repository secrets:

• APPLE_CERTIFICATE
• APPLE_CERTIFICATE_PASSWORD
• APPLE_DEV_IDENTITY
• APPLE_ID
• APPLE_PASSWORD

See: https://hackmd.io/@connoropolous/HkxeYYgzo

There is a sixth environment variable which is useful to set, like this: DEBUG: electron-osx-sign*,electron-notarize*. This allows for useful logging outputs from the signing and notarizing process. This env var is set automatically when running on CI, in the "Release" Github Action.

Versioning For User Data

Each version of the app will either change, or not change, the paths to the user data folders in use by the application.

The user data will be located under a folder with the same name as the value given under the name property of the file electron/package.json in the platform specific appData folder, as specified by appData here: https://www.electronjs.org/docs/latest/api/app#appgetpathname

It is then in a specific sub-folder that relates to one of two types of data:

• source chain and DHT -> databases-${DATABASES_VERSION_ID}
• private keys -> keystore-${KEYSTORE_VERSION_ID}

DATABASES_VERSION_ID and KEYSTORE_VERSION_ID are defined in electron/src/holochain.ts and can be modified as needed in order to jump to new versions of holochain, or a new app DNA.

You can tweak DATABASES_VERSION_ID and KEYSTORE_VERSION_ID independently.

DATABASES_VERSION_ID should be incremented when a new DNA is in use. It will cause users to have to re-create profiles and re-instate data they've previously added.

KEYSTORE_VERSION_ID should be incremented if you want users to have to switch and generate new keys for any reason.

Dependency Versions Information

This project is currently using:

holochain-runner v0.5.2

which has an underlying holochain version of 0.1.0-beta-rc.2

expects an HAPP built with

• HDK v0.1.0-beta-rc.1
• HDI v0.2.0-beta-rc.1

and electron 22

electron-holochain-template's Issues

make a better file system menu

enable logging to file

holochain-runner Crash Report 2

Hi there,

I tried to do a quick set-up using this template but got stuck running npm run devafter successfully installing my dependancies.

This error also comes through if I try to run the lectron command: npm run electron. It seems to be an error regarding the returning 404 when querying the application.happ directory.

electron-holochain-1  | holochain stderr err > Sep 07 23:44:54.257 ERROR holochain_runner::embedded_runner: Conductor returned an error while using a ConductorApi: AppBundleError(FfsIoError(IoError { original: Os { code: 2, kind: NotFound, message: "No such file or directory" }, path: Some("/Users/user/Desktop/CODE/holochain/holochain-electron-template/happ/workdir/application.happ"), backtrace:    0: backtrace::capture::Backtrace::new
electron-holochain-1  |    1: holochain_util::ffs::io_error::IoError::new
electron-holochain-1  |    2: holochain::conductor::conductor::app_impls::<impl holochain::conductor::conductor::Conductor>::install_app_bundle::{{closure}}
electron-holochain-1  |    3: holochain_runner::embedded_runner::install_or_passthrough::{{closure}}
electron-holochain-1  |    4: <core::future::from_generator::GenFuture<T> as core::future::future::Future>::poll
electron-holochain-1  |    5: tokio::runtime::task::core::Core<T,S>::poll
electron-holochain-1  |    6: tokio::runtime::task::harness::Harness<T,S>::poll
electron-holochain-1  |    7: tokio::runtime::scheduler::multi_thread::worker::Context::run_task
electron-holochain-1  |    8: tokio::runtime::scheduler::multi_thread::worker::Context::run
electron-holochain-1  |    9: tokio::macros::scoped_tls::ScopedKey<T>::set
electron-holochain-1  |   10: tokio::runtime::scheduler::multi_thread::worker::run
electron-holochain-1  |   11: tokio::loom::std::unsafe_cell::UnsafeCell<T>::with_mut
electron-holochain-1  |   12: tokio::runtime::task::core::Core<T,S>::poll
electron-holochain-1  |   13: tokio::runtime::task::harness::Harness<T,S>::poll
electron-holochain-1  |   14: tokio::runtime::blocking::pool::Inner::run
electron-holochain-1  |   15: std::sys_common::backtrace::__rust_begin_short_backtrace
electron-holochain-1  |   16: core::ops::function::FnOnce::call_once{{vtable.shim}}
electron-holochain-1  |   17: std::sys::unix::thread::Thread::new::thread_start
electron-holochain-1  |   18: __pthread_deallocate
electron-holochain-1  |  }))
electron-holochain-1  | FATAL PANIC PanicInfo {
electron-holochain-1  |     payload: Any { .. },
electron-holochain-1  |     message: Some(
electron-holochain-1  |         explicit panic,
electron-holochain-1  |     ),
electron-holochain-1  |     location: Location {
electron-holochain-1  |         file: "src/embedded_runner.rs",
electron-holochain-1  |         line: 115,
electron-holochain-1  |         col: 17,
electron-holochain-1  |     },
electron-holochain-1  |     can_unwind: true,
electron-holochain-1  | }
electron-holochain-1  | an unhandled error occurred: Error: Sep 07 23:44:54.257 ERROR holochain_runner::embedded_runner: Conductor returned an error while using a ConductorApi: AppBundleError(FfsIoError(IoError { original: Os { code: 2, kind: NotFound, message: "No such file or directory" }, path: Some("/Users/user/Desktop/CODE/holochain/holochain-electron-template/happ/workdir/application.happ"), backtrace:    0: backtrace::capture::Backtrace::new
electron-holochain-1  |    1: holochain_util::ffs::io_error::IoError::new
electron-holochain-1  |    2: holochain::conductor::conductor::app_impls::<impl holochain::conductor::conductor::Conductor>::install_app_bundle::{{closure}}
electron-holochain-1  |    3: holochain_runner::embedded_runner::install_or_passthrough::{{closure}}
electron-holochain-1  |    4: <core::future::from_generator::GenFuture<T> as core::future::future::Future>::poll
electron-holochain-1  |    5: tokio::runtime::task::core::Core<T,S>::poll
electron-holochain-1  |    6: tokio::runtime::task::harness::Harness<T,S>::poll
electron-holochain-1  |    7: tokio::runtime::scheduler::multi_thread::worker::Context::run_task
electron-holochain-1  |    8: tokio::runtime::scheduler::multi_thread::worker::Context::run
electron-holochain-1  |    9: tokio::macros::scoped_tls::ScopedKey<T>::set
electron-holochain-1  |   10: tokio::runtime::scheduler::multi_thread::worker::run
electron-holochain-1  |   11: tokio::loom::std::unsafe_cell::UnsafeCell<T>::with_mut
electron-holochain-1  |   12: tokio::runtime::task::core::Core<T,S>::poll
electron-holochain-1  |   13: tokio::runtime::task::harness::Harness<T,S>::poll
electron-holochain-1  |   14: tokio::runtime::blocking::pool::Inner::run
electron-holochain-1  |   15: std::sys_common::backtrace::__rust_begin_short_backtrace
electron-holochain-1  |   16: core::ops::function::FnOnce::call_once{{vtable.shim}}
electron-holochain-1  |   17: std::sys::unix::thread::Thread::new::thread_start
electron-holochain-1  |   18: __pthread_deallocate
electron-holochain-1  |  }))
electron-holochain-1  | FATAL PANIC PanicInfo {
electron-holochain-1  |     payload: Any { .. },
electron-holochain-1  |     message: Some(
electron-holochain-1  |         explicit panic,
electron-holochain-1  |     ),
electron-holochain-1  |     location: Location {
electron-holochain-1  |         file: "src/embedded_runner.rs",
electron-holochain-1  |         line: 115,
electron-holochain-1  |         col: 17,
electron-holochain-1  |     },
electron-holochain-1  |     can_unwind: true,
electron-holochain-1  | }
electron-holochain-1  |     at Socket.<anonymous> (/Users/user/Desktop/CODE/holochain/holochain-electron-template/electron/node_modules/@lightningrodlabs/electron-holochain/dist/src/holochain.js:119:33)
electron-holochain-1  |     at Socket.emit (node:events:513:28)
electron-holochain-1  |     at addChunk (node:internal/streams/readable:315:12)
electron-holochain-1  |     at readableAddChunk (node:internal/streams/readable:289:9)
electron-holochain-1  |     at Readable.push (node:internal/streams/readable:228:10)
electron-holochain-1  |     at Pipe.onStreamRead (node:internal/stream_base_commons:190:23)
electron-holochain-1  | holochain stderr err > Well, this is embarrassing.
electron-holochain-1  | holochain-runner had a problem and crashed. To help us diagnose the problem you can send us a crash report.
electron-holochain-1  | We have generated a report file at "/var/folders/vv/ps6s5lf5503_3q4lh4nj_fbh0000gn/T/report-8cbc01c7-3c49-49f0-a869-ecd802ad1df8.toml". Submit an issue or email with the subject of "holochain-runner Crash Report" and include the report as an attachment.
electron-holochain-1  | - Authors: Connor Turland <[email protected]>
electron-holochain-1  | We take privacy seriously, and do not perform any automated error collection. In order to improve the software, we rely on people to submit reports.
electron-holochain-1  | Thank you kindly!
electron-holochain-1  |
electron-holochain-1  | an unhandled error occurred: Error: Well, this is embarrassing.
electron-holochain-1  | holochain-runner had a problem and crashed. To help us diagnose the problem you can send us a crash report.
electron-holochain-1  | We have generated a report file at "/var/folders/vv/ps6s5lf5503_3q4lh4nj_fbh0000gn/T/report-8cbc01c7-3c49-49f0-a869-ecd802ad1df8.toml". Submit an issue or email with the subject of "holochain-runner Crash Report" and include the report as an attachment.
electron-holochain-1  | - Authors: Connor Turland <[email protected]>
electron-holochain-1  | We take privacy seriously, and do not perform any automated error collection. In order to improve the software, we rely on people to submit reports.
electron-holochain-1  | Thank you kindly!
electron-holochain-1  |
electron-holochain-1  |     at Socket.<anonymous> (/Users/user/Desktop/CODE/holochain/holochain-electron-template/electron/node_modules/@lightningrodlabs/electron-holochain/dist/src/holochain.js:119:33)
electron-holochain-1  |     at Socket.emit (node:events:513:28)
electron-holochain-1  |     at addChunk (node:internal/streams/readable:315:12)
electron-holochain-1  |     at readableAddChunk (node:internal/streams/readable:289:9)
electron-holochain-1  |     at Readable.push (node:internal/streams/readable:228:10)
electron-holochain-1  |     at Pipe.onStreamRead (node:internal/stream_base_commons:190:23)
^C>>>>> [PM2 DEV] Stopping current development session
>>>>> [PM2 DEV] Stopping current development session
web-gui-0             | INFO: Gracefully shutting down. Please wait...
electron-holochain-1  | /Users/user/Desktop/CODE/holochain/holochain-electron-template/electron/node_modules/electron/dist/Electron.app/Contents/MacOS/Electron exited with signal SIGINT

When I run npm run happ-pack

I get a lot of errors, but they all seem possibly related. The similarity is that both errors relate to the happ/workdir/ directory. Here is an example:

Error: IO error: ffs::IoError at path '/Users/checoelho/Desktop/CODE/holochain/holochain-electron-template/happ/workdir/./application.dna': No such file or directory (os error 2)
backtrace:
   0: backtrace::capture::Backtrace::new
   1: holochain_util::ffs::io_error::IoError::new
   2: holochain_util::ffs::canonicalize::{{closure}}
   3: <futures_util::future::maybe_done::MaybeDone<Fut> as core::future::future::Future>::poll
   4: <futures_util::future::join_all::JoinAll<F> as core::future::future::Future>::poll
   5: holochain_cli_bundle::cli::HcAppBundle::run::{{closure}}
   6: tokio::runtime::park::CachedParkThread::block_on
   7: tokio::runtime::context::runtime::enter_runtime
   8: hc::main
   9: std::sys_common::backtrace::__rust_begin_short_backtrace
  10: std::rt::lang_start::{{closure}}
  11: std::rt::lang_start_internal
  12: _main


Caused by:
    ffs::IoError at path '/Users/checoelho/Desktop/CODE/holochain/holochain-electron-template/happ/workdir/./application.dna': No such file or directory (os error 2)
    backtrace:
       0: backtrace::capture::Backtrace::new
       1: holochain_util::ffs::io_error::IoError::new
       2: holochain_util::ffs::canonicalize::{{closure}}
       3: <futures_util::future::maybe_done::MaybeDone<Fut> as core::future::future::Future>::poll
       4: <futures_util::future::join_all::JoinAll<F> as core::future::future::Future>::poll
       5: holochain_cli_bundle::cli::HcAppBundle::run::{{closure}}
       6: tokio::runtime::park::CachedParkThread::block_on
       7: tokio::runtime::context::runtime::enter_runtime
       8: hc::main
       9: std::sys_common::backtrace::__rust_begin_short_backtrace
      10: std::rt::lang_start::{{closure}}
      11: std::rt::lang_start_internal
      12: _main
      ```

replace icon images with generic images

Github Actions cache node_modules

holochain-runner Crash Report

Not sure if I have missed something here but holochain-runner seems to be crashing due to an invalid path input ('path must be shorter than libc::sockaddr_un.sun_path"')

After installing deps and running npm run dev, the splash screen opens and hangs.

Console logs:

===============================================================================
--- PM2 development mode ------------------------------------------------------
Apps started         : web-gui,electron-holochain
Processes started    : 2
Watch and Restart    : Enabled
Ignored folder       : node_modules
===============================================================================
web-gui-0  | > [email protected] web
web-gui-0  | > cd web && ADMIN_WS_PORT=1234 APP_WS_PORT=8888 npx serve -p 8080 dist
web-gui-0  |  INFO  Accepting connections at http://localhost:8080
electron-holochain-1  | holochain > Looking for passphrase piped to stdin
electron-holochain-1  | holochain > Found passphrase, continuing...
electron-holochain-1  | holochain > 1
web-gui-0             |  HTTP  9/5/2023 4:47:50 PM ::1 GET /splashscreen
web-gui-0             |  HTTP  9/5/2023 4:47:50 PM ::1 Returned 304 in 28 ms
electron-holochain-1  | holochain stderr err > Well, this is embarrassing.
electron-holochain-1  | holochain-runner had a problem and crashed.

Crash report (report-92693ff7-0798-4178-b1df-3bab097ffda6.toml):

name = 'holochain-runner'
operating_system = 'unix:OSX'
crate_version = '0.5.2'
explanation = '''
Panic occurred in file 'src/embedded_runner.rs' at line 165
'''
cause = 'Could not initialize Conductor from configuration: Other({"error":"InvalidInput","message":"path must be shorter than libc::sockaddr_un.sun_path"})'
method = 'Panic'
backtrace = '''

   0: 0x1047f5504 - core::panicking::panic_fmt::h8c7f3d540a75578f
   1: 0x1047f56ec - core::result::unwrap_failed::h666d2c7e0d130ea0
   2: 0x102d7a194 - <core::future::from_generator::GenFuture<T> as core::future::future::Future>::poll::h24b5e83c31761c6f
   3: 0x102bfb230 - tokio::runtime::park::CachedParkThread::block_on::h175bb71cbf8bc6b0
   4: 0x102b98998 - tokio::runtime::handle::Handle::block_on::h2d83cb82aa02e342
   5: 0x102b504c4 - tokio::runtime::scheduler::multi_thread::worker::block_in_place::h877aff0f87a871d6
   6: 0x102c1200c - holochain_runner::main::h541d30922bf68ccf
   7: 0x102c684e4 - std::sys_common::backtrace::__rust_begin_short_backtrace::h0acbf1778cb0b260
   8: 0x102bc990c - std::rt::lang_start::{{closure}}::h574c11e8d51530ac
   9: 0x10472c550 - std::rt::lang_start_internal::h659a783147314d97
  10: 0x102c12580 - _main'''

make these hardcoded version number references dynamic

The 0.0.1 strings should be dynamic and come from the tag

electron-holochain-template/.github/workflows/release.yml

Lines 85 to 99 in d26d604

	gh release upload "${GITHUB_REF#refs/tags/}" "electron/out/ElectronHolochainTemplate-0.0.1.AppImage" --clobber
	# MacOS
	- name: upload binary (macos only)
	if: ${{ runner.os == 'macOs' }}
	env:
	GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
	run: |
	gh release upload "${GITHUB_REF#refs/tags/}" "electron/out/ElectronHolochainTemplate-0.0.1.dmg" --clobber
	# Windows
	- name: upload binary (Windows only)
	if: ${{ runner.os == 'Windows' }}
	env:
	GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
	run: |
	gh release upload "$($env:GITHUB_REF -replace "refs/tags/")" "electron/out/ElectronHolochainTemplate.Setup.0.0.1.exe" --clobber

discuss nix-shell in the README

add linux app icon

• add example icon
• add documentation to README