Get Started
Welcome to the Getting Started with Holochain guide! This is a four-page guide which will walk you through the process of installing the Holochain development tools and creating a simple forum application. By the end of this guide, you’ll be familiar with the core concepts of Holochain and have a basic understanding of how to develop peer-to-peer applications using the Holochain framework.
How to use this guide
Follow this guide step by step. All steps are essential to create the example applications. No additional code or steps are needed.
There’s a lot of additional explanation that isn’t necessary for building the application, but it’ll help you understand what you’re doing in more depth. Look for the book icon and the ‘Learn more’ heading.
- The examples below use
$to represent your terminal prompt in a UNIX-like OS, though it may have been customized in your OS to appear differently. - We assume that you are reading this guide because you’re a developer who’s new to Holochain but is interested in actually building peer-to-peer distributed applications using a framework that is agent-centric, that provides intrinsic data integrity, is scalable, and runs just on the devices of the participants without relying on centralized servers, blockchain tokens, or other points of centralized control.
- We assume that you’ve at least skimmed Holochain’s Core Concepts or are ready to pop over there when needed.
- Because Holochain’s DNAs are written in Rust, we assume you have at least a basic familiarity with the language. Note, however, that this guide will take you through everything you need to do, step-by-step, so you can follow the steps and learn Rust later. Additionally, Holochain DNAs rarely need to take advantage of the more complicated aspects of the language, so don’t let Rust’s learning curve scare you.
- If you’re new to Rust, you can start your learning journey by reading chapters 1 to 11 in the Rust Book and doing the accompanying Rustlings exercises.
- We also assume that you have basic familiarity with the Unix command line.
1. Introduction to Holochain
Holochain is a framework for building peer-to-peer distributed applications, also known as hApps. It emphasizes agent-centric architecture, intrinsic data integrity, and scalability. Holochain enables developers to build applications that run on just the devices of the participants without relying on centralized servers or blockchain tokens.
2. Installing Holochain development environment
In this section, we’ll walk you through the step-by-step process of installing Holochain, its dependencies, and developer tools on your system so that you can develop hApps.
2.1. Hardware requirements
Before you install the Holochain development environment, make sure your system meets the following hardware requirements:
- 8GB+ RAM (16GB+ recommended)
- 4+ cores CPU (6+ cores recommended)
- 30GB+ available disk space
- High-speed internet connection
This may seem like a lot; it’s mainly due to Rust’s compiler, which requires a lot of system resources.
2.2. Windows prerequisite: WSL2
For Windows users, please note that the Nix package manager, which is used to install and manage the Holochain development environment, only supports macOS and Linux. You’ll need to install Linux under Windows with WSL2 (Windows Subsystem for Linux) (recommended) or dual-boot a Linux OS alongside your Windows 10 or Windows 11 OS to proceed.
Holochain is supported in WSL2 via the Ubuntu distribution.
You’ll also need to install a few packages if you want to run two dev tools, hc spin and hc launch, which start your app’s back end and open its GUI in Electron or Tauri webviews:
sudo apt install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libgtk-3-dev libasound2 adwaita-icon-theme
Read more about these fixes in the Dev Tools Setup guide.
2.3. Set up development environment
Once you’ve ensured that your system meets the hardware requirements and set up WSL2 on Windows or a dual-boot Linux OS (if applicable), you can proceed with the installation of the Nix package manager and the binary package cache for Holochain.
Open a command-line terminal (on Linux, on macOS) and run the following command:
bash <(curl https://holochain.github.io/holochain/setup.sh)
This command downloads the setup script and runs it, installing the Nix package manager and setting up a package cache for Holochain.
2.4. Verify installation
In a new terminal session type:
nix run --refresh -j0 -v github:holochain/holochain#hc-scaffold -- --version
Look out for binaries being copied from holochain-ci.cachix.org:
downloading 'https://holochain-ci.cachix.org/nar/<some-hash>.nar.zst'...
It proves that the package cache is configured correctly.
At the end of the output, Holochain’s scaffolding tool should print its version string:
holochain_scaffolding_cli x.y.z
Congratulations! The Holochain development environment is now set up successfully on your system.
Next up
Now it’s time to download, compile, and try an example Holochain application.
