Quick Start

Last updated: January 23, 2019

Overview

Welcome to the Quick Start guide for getting started with Holochain development. It will guide you through installation. Once you've got things installed, or regardless, read on into a tutorial, the Holochain guidebook, and the API Reference to get going!

If you find an issue with the instructions, please open an issue on the GitHub repo for the documentation site.

If you believe you've found an issue with Holochain, please open an issue on the GitHub repo.

If you just need some general assistance, post all the details on StackOverflow that someone would need to know to help you, and then drop a link to it in the developer community chat.

Install script

The Holochain Rust repository contains automated install scripts for Mac OS X & Linux.

The install scripts are tested against fresh virtual machines regularly during automated testing.

The install scripts will modify the host environment through the most popular package management tooling for each OS.

The package manager is brew on Mac OS X and apt-get for Ubuntu.

The installation scripts are all open source and the same basic steps can be performed manually (see below for details).

Important: Windows users need to install Holochain manually (see below).

Install git

At a minimum you will need to install git to download and manage the Holochain code repository locally.

There are many ways to install git (it is a very common development tool). Instructions for each OS can be found at https://gist.github.com/derhuerst/1b15ff4652a867391f03.

Checkout the Holochain repository

The Holochain Rust repository is hosted on Github at https://github.com/holochain/holochain-rust.

Use git to checkout a specific version of Holochain. For example, to download the latest develop commit:

# develop is the default branch
$ git clone https://github.com/holochain/holochain-rust.git

Run the auto install script

The auto install script will attempt to detect Mac OS X and Linux then run appropriate installation commands.

Important: the script installs and uses package managers such as apt-get, brew and npm.

$ cd path/to/holochain
$ . ./scripts/install/auto.sh

Prerequisites

Step One - Nodejs

End-to-end testing of Holochain apps is done in Javascript executed by Nodejs.
To run the end-to-end tests you need nodejs installed.

Holochain core is tested against nodejs 8.14.1.
Holochain core only supports 8.x LTS versions of nodejs.

To check the currently installed node version run:

node -v

If you don't have a supported nodejs version you can find installation instructions at https://nodejs.org.

Step Two - Rust

The recommended way to write Holochain applications is to use the "Holochain Development Kit" (HDK).

The HDK allows generation of low level web assembly (WASM) code with convenience functions written in the high level Rust language.

In the future there will be HDKs written to a variety of languages, but for now you will need to install and maybe learn some Rust.

We are using a "nightly" release of the Rust langauge.
The Rust community moves very quickly so we "pin" to a specific version to ensure a relatively stable working environment.
Only the pinned nightly version of Rust is compatible with Holochain
To find the current nightly version, check the readme/scripts at https://github.com/holochain/holochain-rust

For installation follow:

Step Three - WebAssembly

Since Holochain code needs to be in WebAssembly, the Rust compilation "target" for WebAssembly is required. This just means that the Rust toolchain knows how to compile Rust code to WebAssembly. You will likely need to restart your terminal, or open a new one, before being able to run the following command. In a terminal, run:

rustup target add wasm32-unknown-unknown

Step Four - ZeroMQ

Being a P2P networking framework, Holochain utilizes a "distributed messaging" library internally called ZeroMQ. For the time being (it is hoped to change this in the future), this must be installed on your computer as well before Holochain can run. The version number that you install must be 4.1 or higher.

Networking Tools

The networking capabilities for Holochain have been developed as a library decoupled from the Rust core. At this time they are written in nodejs (another reason nodejs is a dependency above) and communicate with Holochain via IPC (inter process communication). There is a mock networking implementation in Holochain meaning that technically development of apps can happen without this library, but if you wish to use actual networking this library will be required.

The networking library is called "n3h".

To install it, download it from GitHub, and unzip it: https://github.com/holochain/n3h/releases/tag/v0.0.4-alpha

In a terminal, change directories to the downloaded and unzipped repository. Run:

npm install

npm run bootstrap

This means all the dependencies are installed. Finally, for now, just take note of the full path to the n3h folder on your computer, because you will be needing it later.

Development Tools Installation

If you wish to develop Holochain apps, you will want to install the Holochain developer command line tools.

Step One

When you go to Github, look for one of the downloads that starts with "cli". Go to GitHub and download the appropriate release for your system.

Once you've downloaded it, unpack it, RENAME it "hc" and move the resulting folder to a directory on your computer where you'd like to keep these files long term. As a default, lets assume that it can be this folder called "hc", right under your $HOME or %USERPROFILE% (your user) directory. Now we will have to add this directory to your PATH variable, so that the binary becomes available within your command line. The instructions for this differ, depending on your platform. If you need help with this, read the relevant Help with PATHs section at the bottom of this page.

Windows Note

For the ZMQ dependency to work, move the file "libzmq-v140-mt-4_2_0.dll" that you downloaded into the same "hc" folder as the other files.

If you encounter issues with this, please discuss here.

Step Two

Once the steps for your platform are complete, to confirm that you have the Holochain developer command line tools installed, try running the following command:

hc --version

To read about the commands, and how to get started using them, check out the README for the "hc" command line tools.

Production Tools Installation

If you wish to have a way to run Holochain apps, beyond the simple way available in the development tools, you can do that with the Holochain Conductor, which is capable of mounting configuration files that start up Holochain DNA instances.

Step One

When you go to Github, look for one of the downloads that starts with "conductor". Go to GitHub and download the appropriate release for your system.

Once you've downloaded it, unpack it, RENAME it "holochain" and move the resulting folder to a directory on your computer where you'd like to keep these files long term. As a default, lets assume that it can be this folder called "holochain", right under your $HOME or %USERPROFILE% (your user) directory. Now we will have to add this directory to your PATH variable, so that the binary becomes available within your command line. The instructions for this differ, depending on your platform. If you need help with this, read the relevant Help with PATHs section at the bottom of this page.

Windows Note

For the ZMQ dependency to work, move a copy of the file "libzmq-v140-mt-4_2_0.dll" that you downloaded into the same "holochain" folder as the other files.

If you encounter issues with this, please discuss here.

Step Two

To confirm that you have the Holochain Conductor installed, try running the following command:

holochain --version

To read about the Conductor, and how to get started using it, check out this section of the Guidebook.

Help With PATHs