embedded-holochain-runner

A library that makes it VERY easy to run Holochain as a library, from your own binary, with great defaults

You can find this crate on crates.io: https://crates.io/crates/embedded_holochain_runner

How it will work

datastore_path is most important. If existing persisted Holochain conductor files are found in the given directory, it will simply re-use the admin_ws_port app_ws_port app_id and dnas from that configuration. Otherwise, it will create that directory, and setup your configuration as specified.

It will pair nicely with structopt to make a configurable service. See a simple demo. For a more advanced application using the exported async_main function, shutdown signal, and StateSignal listeners, you can see it in use in the Acorn Holochain application.

In either case,

• first run/installation
• second run/reboot

it will log this to the console when the interfaces are all ready and the app installed or running:

EMBEDDED_HOLOCHAIN_IS_READY

Usage

Cargo.toml

[dependencies]
embedded_holochain_runner = "0.0.103"

[patch.crates-io]
rkv = { git = "https://github.com/holochain/rkv.git", branch = "master" }
lmdb-rkv = { git = "https://github.com/holochain/lmdb-rs.git" }

Assuming you have a compiled Holochain DNA file sitting around at ../dna/sample/sample.dna...

main.rs

use embedded_holochain_runner::*;
const SAMPLE_DNA: &'static [u8] = include_bytes!("../dna/sample/sample.dna");
fn main() {
    // String is like "CellNick"/"SlotId"
    let dnas: Vec<(Vec<u8>, String)> = vec![(SAMPLE_DNA.into(), "sample".into())];
    blocking_main(HcConfig {
        datastore_path: String::from("databases"),
        keystore_path: String::from("keystore"),
        app_id: String::from("my-app-id"),
        dnas,
        admin_ws_port: 1234,
        app_ws_port: 8888,
        proxy_url: String::from("kitsune-proxy://SYVd4CF3BdJ4DS7KwLLgeU3_DbHoZ34Y-qroZ79DOs8/kitsune-quic/h/165.22.32.11/p/5779/--"),
        event_channel: None,
    })
}

It will clearly log its configuration to the console.

RUST_LOG environment variable can be set to get details logs from Holochain. Those logs are by default suppressed.

Events

if you pass an event_channel, which should be of type: Option<tokio::sync::mpsc::Sender<StateSignal>> where StateSignal can be imported via use embedded_holochain_runner::StateSignal, you can listen for the following events, to trigger external actions.

It looks like:

pub enum StateSignal {
    // will be only one or the other of these
    IsFirstRun,
    IsNotFirstRun,
    // are sub events after IsFirstRun
    CreatingKeys,
    RegisteringDna,
    InstallingApp,
    EnablingApp,
    AddingAppInterface,
    // Done/Ready Event, called when websocket interfaces and
    // everything else is ready
    IsReady,
}

Bootstrap Networking Service

This library is currently pointed at the https://bootstrap-staging.holo.host node discovery service.

Holochain Version

The HDK used for your DNA should match the version used in this library, which is listed below. Such as:

Zome Cargo.toml

[dependencies]
# use whatever hdk uses
serde = "*"
hdk = "0.0.109"

Currently bundles Holochain version: 0.0.109 (October 6, 2021).