Holochain Forum

A beginner's experiences on the Holochain

I collect here some experiences about the use of Holochain in GoWood Proof of Concept. I hope that you find this reflection useful.

In short, the idea of the proof of concept was to experiment better ways to track wood material. The technical PoC was just a part of whole research project, and Holochain was just a part of PoC.

Source code and more detailed technical description are available here:

As disclaimer: Holochain part in the PoC is written in less than 2 weeks by a team that didn’t have any experience in Rust or Holochain in advance. The implemention is good enough within the scope of PoC but far from ideal. It would have been cool if we had had time to use Holochain more extensively and properly. E.g. we didn’t have time to think proper use of DPKI and I’m aware that the function call validation is simplistic.

On setting up development environment

The biggest pain for use related setting up development environment for Windows. It was painful for following reasons:

  • Vagrant + Virtual Box setup didn’t work, because Virtual Box is not compatible with Hyper-V and Hyper-V is used in the latest versions of Docker (for Windows). Maybe there is nowadays a way to make Vagrant work with Hyper-V, I don’t know. I wasted days in trying that few years ago and managed to mess up my network setting so badly that I decided to not try again within next decade years or so.
  • Windows Update from Windows insider program just failed to install the needed update so I could not use WSL2. My colleague probably didn’t even try it.

In the end, we managed to make development environment work pretty nicely with Docker (also in WSL v. 1). Basically, the idea is to mount source code to docker container as a volume. I used VSCode on Windows as code editor and my colleague used Emacs (inside WSL v. 1).

I notice that people are working to improve documentation here. Anyway, if there is need, I can contribute by writing instructions how to make Holochain work on Windows with Docker (and Hyper-V) and optionally WSL v. 1 (if you prefer Linux tooling for development).

On documentation

Holochain documentation is rather mixed. There is a lot of good stuff and a lot of confusing stuff. For instance description of core concepts and API documentation in docs.rs are pretty good and clear. On the other hand tutorials and deep dive documentation are — well — confusing.

If I have time, I’ll write a blog post on Holochain to my company (Flowa) blog. There’s a lot of good idea in Holochain, the world should know about. I’m also pondering whether I should contribute and improve tutorials. Is someone already working on improved tutorials already?

On tooling: hc and holochain

It took quite a while to realized what is relation between hc and holochain. hc CLI tool turned out too limited for us and we ended up using holochain command to run conductor. Unlike in holochain, there is no -c flag (use configuration file) in hc and hence, it seems to be impossible to have (a) multiple configurations for instances, (b) run multiple instances during development and © make admin interfaces work with hc. (It’s also possible that I just failed to figure out how.)

There’s also a lot of good in Holochain tooling. We (me and my colleague) especially appreciated e2e testing tool Tryorama. It’s is great. In addition to the partially outdated documentation, the only problem we had in it related logging: it was hard figure out how to set log level right when you want to have less logging. By default there is a lot of debug logging that is irrelevant in many cases.

I spotted also few (non-critical) bugs from the tooling but I haven’t had time to file them as issues (sorry).

On compiler and macros

I truly like new hdk2 macros. Comparing the older version I saw in tutorial and old documentation, the code is a lot more readable. Unfortunately, if you mess up with types, you get in some cases very confusing error from compiler. I have not checked if there is already a issue on this, if not I’ll report one within next few days. I don’t know if the also macros caused produced sometime similar almost useless error message. Then again, in the most cases compiler errors are just great.

In overall

In overall, I like Holochain, and I’m considering whether I should contribute in the project. I can see myself using it in future. The biggest pains and frustrations related development environment and documentation (and lack of it). In addition, there were some small nuisances and bugs that slowed you down, but nothing critical. Given the status of Holochain, small nuisances and bugs were expected.


Hi @ilmirajat, thank you kindly for your detailed writeup and feedback. It means so much that you have taken the time to provide feedback, but that you also want to help make things better.

You are right, there are many things that could improve with our documentation. Please know that the Guide has to be revamped.

We would appreciate any improvements and changes you may have to our documentation and/or tutorials. The best way to suggest/make changes is to submit a PR or an issue.

On every dev docs page, there is an option to edit. Please click edit and you will be directed to log the issue via GitHub. Please let me know if you need further assistance.

As for the other feedback, we’ll take some time to reflect and where appropriate add it to our Holochain Feedback board. Our core devs are tracking this specific feedback area so some will appreciate your feedback.

If you find any bugs or issues with Holochain Core, feel free to submit an issue via the Holochain Rust repo.

1 Like

The best way to start is to contribute where you feel comfortable. Start with documentation and we can connect with you if you would like to discuss further.

Feel free to draft a write up and submit a PR and/or post on the Forum.

@newprometheus created a NixOs Install Guide. He did such a great job. We decided to add it to our Dev Portal. So feel free to share on the Forum.

1 Like

I should document how I got up and running with a DigitalOcean droplet, Vscode and Nix Environment Selector extension, very smooth experience!

Got sick of trying to get things working with Windows/WSL/Vagrant and just set up a cloud development environment. Big benefit is I can access the same exact environment reliably from any device, even my old and shitty ThinkPad or my phone - the droplet does all the work. Very cheap too.


Yes, please do. We encourage more people to document and share about their experience. Feel free to post the write up in the get started section. The information could benefit someone who may have a similar setup. Thank you

@ilmirajat thanks so much for taking the plunge and using Holochain in your PoC; it warms my heart to know that people are doing that. And thank you also for coming back and sharing your experiences; this is super valuable to us.

Sorry to hear you had trouble getting both the Vagrant/VBox and your own WSL2/Nix attempt to work; we’re painfully aware that the windows dev experience is not great right now. I have also wasted days (and hardware money) trying to get Docker and VirtualBox to play nicely on Windows; I now hate Hyper-V :smiley: Hoping that WSL2 will land and any Windows/Nix bugs will be resolved soon; this’ll make things much easier for us and Windows devs.