Note: this tutorial has been deprecated.

As of 9/2022 a better way to build your first app is to use the scaffolding generator.

How to build a hApp (Holochain App): The Basics

This README last updated: 2021-12-14

Holochain revision: 0.0.119 December 8, 2021 HDK version: 0.0.116

This project has a complementary guide at the "call your hApp tutorial", and interacts with that code via a clean separation at the "network layer". This project is called by that project over a Websocket based network connection. The versions of holochain used may or may not be up-to-date and match this tutorial, so we recommend double checking that and not attempting to utilize it if it is different.

Welcome to this project here to help you build and run your first hApp! It covers the very basics only. If you haven't previously read the article on "Application Architecture" on the developer documentation it could be helpful to do so now, or at any point during this tutorial.

Important documentation

• HC CLI docs
• HDK docs

Steps

0. Install nix-shell

1. If you haven't yet, install the nix-shell.

Note that you don't need to do the nix-shell https://holochain.love step, since in this repository we provide an example default.nix file that provides the appropriate versions for the binaries that you will need.

2. Activate the holochain cachix with:

nix-env -iA cachix -f https://cachix.org/api/v1/install
cachix use holochain-ci

3. Enter the nix-shell for this repository by running nix-shell . in this folder. This may take a while the first time you run it.
   • Verify everything is working fine by typing the command hn-introspect which should give you output showing the version of the holochain tools installed:

$ hn-introspect 
List of applications and their version information

v0_0_119
- hc-0.0.20: https://github.com/holochain/holochain/tree/holochain-0.0.119
- holochain-0.0.119: https://github.com/holochain/holochain/tree/holochain-0.0.119
- kitsune-p2p-proxy-0.0.15: https://github.com/holochain/holochain/tree/holochain-0.0.119
- lair-keystore-0.0.9: https://github.com/holochain/lair/tree/v0.0.9
...

1. Write your Zomes

Each zome is a Rust crate. See zomes/whoami and zomes/numbers for examples. For a more complete list of examples of a wide spectrum of functionality of Holochain and the HDK, check out this folder of examples from Holochain.

2. Build your Zomes into WebAssembly (WASM)

When you want to build your zomes into WebAssembly (wasm), simply run

CARGO_TARGET_DIR=target cargo build --release --target wasm32-unknown-unknown

and they will be available in target/wasm32-unknown-unknown/release/.

You will have to rerun this any time you redo step 1 (edit your Zomes).

3. Package your "Wasms" into a DNA file

1. Create a new dna workdir with hc dna init <DNA_FOLDER>. This will create a dna.yaml in it with the necessary initial configuration.
2. Add your zomes to the dna.yaml file with references the *.wasm files you built in the previous step (see workdir/dna/dna.yaml for examples).
3. Run the following command to package your Wasms into a DNA file per your dna.yaml:

hc dna pack workdir/dna

This will produce a demo.dna file as a sibling of the workdir/dna directory.

You will have to rerun step 3.3 (hc dna pack) of this step any time you redo primary step 2 (change and rebuild your Wasms).

4. Package your DNAs into a happ file

hApps (holochain apps) are bundled as aggregations of different DNAs.

1. Create a new happ workdir with hc app init <HAPP_FOLDER>. This will create a happ.yaml in it with the necessary initial configuration.
2. Add the DNA bundle created in the previous step to the new happ.yaml file (see workdir/happ/happ.yaml for an example).
3. Run the following command to package your DNAs into a happ bundle per your happ.yaml:

hc app pack workdir/happ

This will produce a demo-happ.happ file as a child file in the workdir/happ directory.

You will have to rerun steo 4.3 (hc app pack) of this step any time you redo primary step 3 (change and rebuild your Dna).

5. Testing

To run the tryorama tests, make sure you have built the .happ file as specified in the steps above and then execute these commands:

cd tests
npm install
npm test

This will output something similar to this:

11:00:17 info:
☸☸☸ [[[CONDUCTOR c0]]]
☸ Conductor ready.
☸
11:00:17 [tryorama] info: Conductor 'c0' process spawning completed.
App Port spun up on port  46587
ok 1 should be strictly equal
11:00:20 [tryorama] info: conductor 'c0' exited with code null
FIXME: ignoring onLeave

1..1
# tests 1
# pass  1

# ok

You can look at tests/src/index.ts and have a look at the tests. You can also look at the tryorama documentation.

If you make edits to your Zomes (step 1), you will need to perform steps 2 and 3 again in order for the changes to be reflected in the running of your tests, since it looks at the packed DNA file.

6. Running your happ

To run the happ bundle directly, execute this command replacing workdir/happ for the directory in which you have your *.happ file:

hc sandbox generate workdir/happ --run=8888

which should yield something similar to this:

hc-sandbox: Created config at /tmp/tmp.2Vg2Ml2jO6/io6SQmBmBRX3oBroT0YkG/conductor-config.yaml

Conductor ready.
hc-sandbox: Created ["/tmp/tmp.2Vg2Ml2jO6/io6SQmBmBRX3oBroT0YkG"]

Conductor ready.
hc-sandbox: Running conductor on admin port 45843
hc-sandbox: Attaching app port 8888
hc-sandbox: App port attached at 8888
hc-sandbox: Connected successfully to a running holochain

Now you'll have holochain waiting with an AppInterface for a connection at port 8888. You also have holochain waiting with an AdminInterface on port (subject to vary) 45843 as mentioned in the logs.

Now that you're here, you can connect to the app interface from a client and call your Zome functions! How to do so is covered elsewhere, including a companion tutorial specifically compatible with this repository called "How to call your hApp". There are libraries for helping from different languages, such as javascript and Rust, but it is entirely possible from other languages with Websockets functionality, if you follow the protocol.

If you have rerun step 4 (rebuilt your hApp) and you are prepared to lose any data in your sandbox, stop the process and run hc sandbox clean, then rerun the step 6 command to have a fresh sandbox with your updated hApp.

You can look at the documentation of hc sandbox to learn more on how to manage sandboxes. For a quick helper: in case you shut down your running conductor, you can start it again using hc sandbox run.

Note: hc sandbox and its derivates are at a prototype stage and subject to change.

Next steps

Here you have useful documentation for holochain core utilities:

• Core Concepts
• HDK documentation
• HDK usage examples
• Tryorama documentation
• Conductor API

Here you can find useful resources:

• Help & How To Wiki: community contributed how tos and explainers
• Holochain Gym: a step-by-step collection of exercises to get you started in holochain development.
• Acorn: the most complete holochain application up-to-date, full-stack.
• Holochain Open Dev: collection of small holochain modules.
• RSM playtime: deep dive video series on holochain rsm.

Contribute

Holochain is an open source project. We welcome all sorts of participation and are actively working on increasing surface area to accept it. Please see our contributing guidelines for our general practices and protocols on participating in the community, as well as specific expectations around things like code formatting, testing practices, continuous integration, etc.

• Connect with us on our forum

License

Copyright (C) 2019-2021, Holochain Foundation

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.