Support for windows in the documentation needs a complete overhaul

[davidkel]

The references to using windows with hyperledger fabric are minimal and potentially inaccurate now for example in
https://hyperledger-fabric.readthedocs.io/en/release-2.2/install.html#install-samples-binaries-and-docker-images
It talks about a docker quick start terminal, yet I cannot find that in my docker desktop installation
Also in https://hyperledger-fabric.readthedocs.io/en/release-2.2/prereqs.html#windows-extras
It talks about using windows powershell, however that may be ok for some commands but all the scripts that are in fabric-samples are for bash which obviously won't work in powershell.

The documentation for using windows requires a complete overhaul and should cover

• being able to get fabric running on a windows machines (ie be able to make use of all the contents of fabric-samples) for the purposes of developing fabric applications
• using windows as a platform to build and run fabric yourself (for development purposes only such as contributing to the fabric code base)

This should then give a complete solution for using Windows/Mac or Linux as a development platform

[davidkel]

The documentation between 2.2 and 2.4 has changed, but still the 2.4 documentation is not good enough to get things working on windows. The revamp for an end user wanting to install fabric and use fabric samples should focus around using WSL2 and Docker Desktop

For a user of fabric point of view for Windows

1. Ensure WSL is enabled and that it enables WSL 2 support. Some info here https://docs.microsoft.com/en-us/windows/wsl/install however it misses the part where you might have to enable windows features ie wsl + virtual machine platform
2. Ensure you have a distro installed such as Ubuntu-20.04 and that it is using WSL2 (refer to above microsoft docs)
3. Install Docker Desktop
4. In settings of Docker Desktop go to Resources->WSL Integration and ensure the checkbox to enable integration is checked. You should also see your distribution listed (if you don't then it means you need to convert it from wsl1 to wsl2). Ensure you enable your distribution by toggling the switch next to your distribution to on
5. jq may need to be installed as currently described into your distro. If you used ubuntu then sudo apt install jq should suffice
6. go is also optional and may be installed

Then use your wsl2 distro shell to perform the commands as per the documentation

I also tried Git Bash but couldn't make it work

It may be possible to install other more native bash environments on windows to make it work. Also you might be able to make wsl1 bash environment to work but no help on this can be provided
my distro had curl and git already, but they may have to be installed

[davidkel]

For a developer of fabric point of view

Developers should be far more savvy, but I don't think we can recommend trying to develop fabric or any of it's components on native windows, again it requires a bash environment as all the scripts in different fabric repos will be written for bash for linux/mac users so again it comes down to first finding a native bash environment that's reliable for this env (WSL2 is not a native environment as it runs in a linux VM). Fabric are not going to add support for native windows as it's not a common platform among maintainers and contributors

The setup described in the previous comment should easily suffice a developer of fabric as well. The more advanced option which won't be documented but could be used is to not use docker desktop but install docker and docker-compose in your WSL2 distro use google (other search engines are also available) to help on this as WSL2 distros currently don't use systemd

Also VSCode is the highly recommended IDE for this environment as it provides extensions for tight integration into WSL2

[denali49]

Your are correct Dave, but I have found a better alternative for Windows. I have found that using Dev Containers in VSCode overcomes almost all of these issues. I am surprised more people are not doing this as the only requirements are having VSCode installed and the remote containers extension installed in VSCode. I normally use Mac OSX but when I have to use Windows I use Dev Containers in VSCode to containerize the development environment. Also with Dev Containers in VSCode, the project could publish a pre-built image that already has the requirements. Granted you still need Docker Desktop for Windows with WSL2, but you can also install Docker in the Dev Container and you get native bash, zsh, and other tools in the container eliminating the need for gitbash. Check it out here https://code.visualstudio.com/docs/remote/containers <https://code.visualstudio.com/docs/remote/containers> Chris Chris Gabriel, Founder Hyperchain Labs https://hyperchainlabs.eth.limo <https://hyperchainlabs.eth.limo/>

…

On Jan 20, 2022, at 5:38 AM, Dave Kelsey ***@***.***> wrote: For a developer of fabric point of view Developers should be far more savvy, but I don't think we can recommend trying to develop fabric or any of it's components on native windows, again it requires a bash environment as all the scripts in different fabric repos will be written for bash for linux/mac users so again it comes down to first finding a native bash environment that's reliable for this env (WSL2 is not a native environment as it runs in a linux VM). Fabric are not going to add support for native windows as it's not a common platform among maintainers and contributors The setup described in the previous comment should easily suffice a developer of fabric as well. The more advanced option which won't be documented but could be used is to not use docker desktop but install docker and docker-compose in your WSL2 distro use google (other search engines are also available) to help on this as WSL2 distros currently don't use systemd — Reply to this email directly, view it on GitHub <#2993 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AH5FSLQMW34YG3VZQ7C3JRTUW7X3FANCNFSM5GTKCI3A>. You are receiving this because you are subscribed to this thread.

[davidkel]

@denali49 Thanks for that I will take a look, sounds interesting. VSCode is an option for the developer but I didn't want to mandate an IDE for the instructions as I know that the choice of IDE can be quite emotive. We may suggest VSCode in the final documentation and some recommendations.
I'm not sure the fabric maintainers will want to publish a pre-built dev image. I know the project tried something similar in the past using vagrant but it quickly got stale as there was no interest in maintaining it and it would only be VSCode specific ?

As it still requires WSL2 and Docker Desktop for Windows which is what I am recommending here it should be easy for a developer to then take advantage of this capability if they so wish in the same way you have.

I mentioned git bash here when I was looking at a more native option (ie not WSL2) and wanted to cover alternatives and it was also the recommended tool in the past for windows fabric users, but as I couldn't even get it to work it was a non starter.

[davidkel]

on this page there is a reference to windows as well
https://hyperledger-fabric.readthedocs.io/en/latest/write_first_app.html
For windows we will continue to recommend using the wsl2 shell and follow the instructions noting that they install a linux version of node as all instructions use unix file separators and so would be the simplest update here.
Also we can remove the section about installing build-essential which is also ubuntu specific but is redundant now as you only need native build tools for pkcs11.

as a note, advanced windows users will know that they could mount the wsl2 file system as a drive on windows (you need to use an explicit drive rather than a UNC path as only powershell supports UNC directly and some commands would try to launch cmd.exe which can't support UNC directly). There you would be able to run the client samples directly in native windows with the fabric-samples directory stored in the wsl2 disto file system

[davidkel]

Summary of links to be updated
https://hyperledger-fabric.readthedocs.io/en/latest/prereqs.html
https://hyperledger-fabric.readthedocs.io/en/latest/install.html
https://hyperledger-fabric.readthedocs.io/en/latest/dev-setup/devenv.html
https://hyperledger-fabric.readthedocs.io/en/latest/write_first_app.html
https://hyperledger-fabric.readthedocs.io/en/latest/tutorial/commercial_paper.html
https://hyperledger-fabric.readthedocs.io/en/latest/test_network.html

need to find a way to keep the details about if you do decide to check out repo's under native windows (not wsl2)