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.
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).
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.
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
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
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:
If you don't have a supported nodejs version you can find installation instructions at https://nodejs.org.
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
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
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.
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 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.
If you wish to develop Holochain apps, you will want to install the Holochain developer command line tools.
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.
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.
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:
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.
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.
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.
To confirm that you have the Holochain Conductor installed, try running the following command: