geomind_research/holo_ledger
20
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

development flow hololedger #2

New issue
Closed
opened 2026-01-06 08:02:34 +00:00 by despiegk · 1 comment
despiegk commented 2026-01-06 08:02:34 +00:00
Owner
Copy link

Story: Easy Local Holochain Development & Deployment

Goal

Make it trivial for any developer to:

  1. Install everything needed to run a Holochain conductor
  2. Build & package the DNA
  3. Start / stop the node reliably
  4. Interact with the chain from Rust
  5. Contribute without understanding Holochain internals first

This repo should feel like:

`./install.sh
./run.sh

Non-Goals

  • No production ops (K8s, monitoring, scaling)
  • No deep Holochain theory
  • No UI requirements

Repository Structure (example)

repo/
├── dna/
│   ├── zomes/
│   │   └── example_zome/
│   ├── Cargo.toml
│   └── dna.yaml
│
├── conductor/
│   ├── conductor-config.yaml
│   └── keystore/
│
├── client/
│   ├── Cargo.toml
│   └── src/main.rs
│
├── scripts/
│   ├── install.sh
│   ├── build.sh
│   ├── run.sh
│   ├── stop.sh
│   ├── clean.sh
│   └── package.sh
│
├── zinit/
│   └── holochain.yaml
│
├── .github/workflows/
│   └── build-holochain.yml
│
└── README.md

Developer Flow (Happy Path)

git clone …
cd repo
./scripts/install.sh
./scripts/build.sh
./scripts/run.sh
./scripts/client_example.sh

Scripts (Required Behavior)

scripts/install.sh

Purpose: one-time setup

Responsibilities:

  • Install Rust (if missing)

  • Install Holochain binaries:

    • holochain
    • hc

  • Create local directories:

    • conductor/keystore
    • conductor/data

  • Validate versions

Output:

✓ Rust installed
✓ Holochain installed
✓ Environment ready

scripts/build.sh

Purpose: build everything

Responsibilities:

  • Build all zomes (cargo build --release)
  • Package DNA (hc dna pack)
  • Place .dna file in conductor/

scripts/run.sh

Purpose: start a local node

Responsibilities:

  • Start holochain conductor

  • Load conductor config

  • Run in:

    • screen or
    • zinit (preferred if installed)

Example (screen fallback):

screen -S holochain -dm holochain conductor -c conductor/conductor-config.yaml

scripts/stop.sh

Purpose: clean shutdown

  • Stop screen session or zinit service
  • Do not delete data

scripts/package.sh

Purpose: reproducible artifact

  • Build DNA

  • Bundle:

    • .dna
    • conductor-config.yaml

  • Output to dist/

zinit Integration

We support zinit first-class, but it’s optional.

zinit/holochain.yaml

exec: holochain conductor -c conductor/conductor-config.yaml
oneshot: false
after:
  - network

If zinit is installed:

zinit install ./zinit/holochain.yaml
zinit start holochain

If not → scripts fall back to screen.

Rust Client (Required Example)

Purpose

Demonstrate:

  • Connecting to a local conductor
  • Calling a zome function
  • Reading a response

Location

client/src/main.rs

Minimal Example

use holochain_client::AppWebsocket;
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let ws = AppWebsocket::connect("ws://localhost:8888").await?;

    let result = ws.call_zome(
        "example-app",
        "example_zome",
        "ping",
        json!({"msg": "hello"}),
        None,
    ).await?;

    println!("Response: {:?}", result);
    Ok(())
}

This is the reference client contributors copy from.

Auto Builders (CI)

.github/workflows/build-holochain.yml

Triggered on:

  • PR
  • main branch push

Responsibilities:

  • Install Rust
  • Install Holochain
  • Build all zomes
  • Pack DNA
  • Fail fast on errors

No publishing, no deploy — just confidence.

README Requirements

README must answer only:

  1. How do I install?
  2. How do I run a node?
  3. How do I call the chain?
  4. Where do I change logic?

No long explanations.

Definition of Done

  • New developer can run everything in <15 minutes
  • No manual steps outside scripts
  • Works on macOS + Linux
  • Rust client compiles and talks to the conductor
  • Node can be started/stopped cleanly
# Story: Easy Local Holochain Development & Deployment ## Goal Make it **trivial for any developer** to: 1. Install everything needed to run a **Holochain conductor** 2. Build & package the DNA 3. Start / stop the node reliably 4. Interact with the chain from **Rust** 5. Contribute without understanding Holochain internals first This repo should feel like: > `./install.sh > ./run.sh --- ## Non-Goals * No production ops (K8s, monitoring, scaling) * No deep Holochain theory * No UI requirements --- ## Repository Structure (example) ``` repo/ ├── dna/ │ ├── zomes/ │ │ └── example_zome/ │ ├── Cargo.toml │ └── dna.yaml │ ├── conductor/ │ ├── conductor-config.yaml │ └── keystore/ │ ├── client/ │ ├── Cargo.toml │ └── src/main.rs │ ├── scripts/ │ ├── install.sh │ ├── build.sh │ ├── run.sh │ ├── stop.sh │ ├── clean.sh │ └── package.sh │ ├── zinit/ │ └── holochain.yaml │ ├── .github/workflows/ │ └── build-holochain.yml │ └── README.md ``` --- ## Developer Flow (Happy Path) ```bash git clone … cd repo ./scripts/install.sh ./scripts/build.sh ./scripts/run.sh ./scripts/client_example.sh ``` --- ## Scripts (Required Behavior) ### `scripts/install.sh` Purpose: **one-time setup** Responsibilities: * Install Rust (if missing) * Install Holochain binaries: * `holochain` * `hc` * Create local directories: * `conductor/keystore` * `conductor/data` * Validate versions Output: ``` ✓ Rust installed ✓ Holochain installed ✓ Environment ready ``` --- ### `scripts/build.sh` Purpose: **build everything** Responsibilities: * Build all zomes (`cargo build --release`) * Package DNA (`hc dna pack`) * Place `.dna` file in `conductor/` --- ### `scripts/run.sh` Purpose: **start a local node** Responsibilities: * Start `holochain conductor` * Load conductor config * Run in: * `screen` **or** * `zinit` (preferred if installed) Example (screen fallback): ```bash screen -S holochain -dm holochain conductor -c conductor/conductor-config.yaml ``` --- ### `scripts/stop.sh` Purpose: clean shutdown * Stop `screen` session or zinit service * Do **not** delete data --- ### `scripts/package.sh` Purpose: reproducible artifact * Build DNA * Bundle: * `.dna` * `conductor-config.yaml` * Output to `dist/` --- ## zinit Integration We support **zinit first-class**, but it’s optional. ### `zinit/holochain.yaml` ```yaml exec: holochain conductor -c conductor/conductor-config.yaml oneshot: false after: - network ``` If zinit is installed: ```bash zinit install ./zinit/holochain.yaml zinit start holochain ``` If not → scripts fall back to `screen`. --- ## Rust Client (Required Example) ### Purpose Demonstrate: * Connecting to a local conductor * Calling a zome function * Reading a response ### Location ``` client/src/main.rs ``` ### Minimal Example ```rust use holochain_client::AppWebsocket; use serde_json::json; #[tokio::main] async fn main() -> anyhow::Result<()> { let ws = AppWebsocket::connect("ws://localhost:8888").await?; let result = ws.call_zome( "example-app", "example_zome", "ping", json!({"msg": "hello"}), None, ).await?; println!("Response: {:?}", result); Ok(()) } ``` > This is **the reference client** contributors copy from. --- ## Auto Builders (CI) ### `.github/workflows/build-holochain.yml` Triggered on: * PR * main branch push Responsibilities: * Install Rust * Install Holochain * Build all zomes * Pack DNA * Fail fast on errors No publishing, no deploy — just **confidence**. --- ## README Requirements README must answer **only**: 1. How do I install? 2. How do I run a node? 3. How do I call the chain? 4. Where do I change logic? No long explanations. --- ## Definition of Done * New developer can run everything in <15 minutes * No manual steps outside scripts * Works on macOS + Linux * Rust client compiles and talks to the conductor * Node can be started/stopped cleanly
lee commented 2026-01-08 13:27:24 +00:00
Member
Copy link

Work is done, scripts have been added in scritps dir. Using these scripts a user can install prerequisites, start a node with the app loaded, and perform some examples using the client (also in repo)

Work is done, scripts have been added in scritps dir. Using these scripts a user can install prerequisites, start a node with the app loaded, and perform some examples using the client (also in repo)
lee closed this issue 2026-01-09 10:55:28 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
lee
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
geomind_research/holo_ledger#2
No description provided.