docs: refine and expand getting-started, improve navigation (GalaChai…

…n#474) * docs: refine and expand getting-started, improve navigation * fix: galachain discord url * docs: minor refinements to galachain.md
sentientforest · Dec 19, 2024 · c963dcc · c963dcc
1 parent 1d7aacc
commit c963dcc
Show file tree

Hide file tree

Showing 5 changed files with 190 additions and 68 deletions.
diff --git a/docs/.pages b/docs/.pages
@@ -2,6 +2,9 @@ nav:
     - Home: index.md
     - GalaChain: galachain.md
     - Getting Started: getting-started.md
+    - Test Net Deployment: from-zero-to-deployment.md
+    - Troubleshooting: troubleshooting.md
+    - Windows WSL for Development: windows-wsl.md
     - Galachain Development: chaincode-development.md
     - Galachain Client: chaincode-client.md
     - Galachain Testing: chaincode-testing.md

diff --git a/docs/galachain.md b/docs/galachain.md
@@ -2,37 +2,50 @@
 
 ## What is GalaChain?
 
-GalaChain is a layer 1 blockchain designed to be the foundation of Web3 Gaming, Entertainment and more.
+GalaChain is a Layer 1 (L1) Blockchain designed to be the foundation of Web3 Gaming, Entertainment and more.
 
-## Why is GalaChain?
+## Why create GalaChain?
 
-When [Gala Games](https://gala.games) began integrating blockchain technology with games, we quickly realized that existing blockchain technology was not built to support the kinds of functionality that players and developers desired in Web3 gaming. We set out on a quest to build something different. As Gala has evolved, we recognize even more Web3 use cases that GalaChain is perfect for. We're building a foundation for Web3 Gaming, Entertainment and beyond.
+When [Gala Games](https://gala.games) began integrating blockchain technology with games, we quickly realized that existing blockchain technology was not built to support the kinds of functionality that players and developers desired in Web3 gaming. 
+
+We set out on a quest to build something different. As Gala evolved, we recognized even more Web3 use cases that GalaChain could serve perfectly. 
+
+We're building a foundation for Web3 Gaming, Entertainment, and beyond.
 
 ## What kind of technology is GalaChain?
 
-The core technology that GalaChain is built on is [Hyperledger Fabric](https://www.hyperledger.org/projects/fabric).
-We have built infrastructure and code to add capabilities to easily onboard games and users.
-Now it's very straightforward to write contracts using typescript.
-We've also created a Token contract that can be implemented in any channel.
-This immediately gives the channel access to native Token operations such as transfer, mint, allowances, swapping, lending, and more.
+The core technology at the foundation of GalaChain is [Hyperledger Fabric](https://www.lfdecentralizedtrust.org/projects/fabric).
+
+We have built infrastructure and written code to add capabilities to easily onboard games and users.
+Now it's very straightforward to write contracts using [TypeScript](https://www.typescriptlang.org/).
+
+We've also created a Token contract that can be implemented in any channel. This contract immediately gives the channel access to native Token operations such as transfer, mint, allowances, swapping, lending, and more.
+
+Read more about the integration of GalaChain with Hyperledger Fabric in this [2024 blog post](https://www.lfdecentralizedtrust.org/blog/galachain-leveraging-hyperledger-fabric-to-create-the-ultimate-entertainment-blockchain) published with the [LF Decentralized Trust](https://www.lfdecentralizedtrust.org/).
+
+## When will GalaChain be availalbe?
 
-## When is GalaChain?
+Now! GalaChain has already been integrated into live products including SpiderTanks, Music, PokerGO, and Champions Arena. Many more are being onboarded in preparation for launch.
 
-Now! GalaChain has already been integrated into live products including SpiderTanks, Music, PokerGO, and Champions Arena.
-Many more are being onboarded in preparation for launch.
 Additionally, we're working incrementally toward broader public access and participation.
 
-## Where do nodes come in?
+## Where do Nodes come in?
+
+We've got a lot of ideas about that! 
+
+The first GalaChain workload that will be on Nodes is likely to be one that helps perform bridge transaction verifications.
 
-We've got a lot of ideas about that! The first GalaChain workload that will be on nodes is likely to be one that helps perform bridge transaction verifications.
 More info coming soon!
 
 ## How fast is GalaChain?
 
 Super-fast (or slow).
+
 One of the cool features of GalaChain is that each channel can be configured for different performance options.
-Maybe your product wants to drop big chunks of data in each block and there's time between transactions, or you could have small data, moving really fast.
-It's configurable! We typically don't talk about tx/s simply because it's relative to the use case and so one data point may not be useful for everyone.
+
+Maybe your product wants to drop big chunks of data in each block and there's time between transactions, or you could have small data, moving very quickly.
+
+It's configurable! We typically don't talk about transactions per second (tx/s) simply because this metric is relative to the use case. One data point may not be useful for everyone.
 
 ## GalaChain for Publishers
 

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -1,18 +1,128 @@
 # Getting started
 
-## Option 1: Local Environment (Linux, MacOS, or Windows with WSL)
+To write application chaincode for GalaChain, a prospective developer will want at least some familiarity with TypeScript and general experience working with [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript), [Node.js](https://nodejs.org/), and the wider [npm](https://www.npmjs.com/) ecosystem. 
 
-> If you are using Windows with WSL don't forget to enable integration with WSL on Docker Desktop.
+A broad understanding of working with the command line, backend web application development, and asynchronous programming will also be useful for all chaincode developers.
 
-[How to use Windows with WSL](./windows-wsl.md)
+We aim to be beginner-friendly. Additional documentation and onboarding resources are forth coming, and community assistance is available in the [GalaChain Discord Server](https://discord.gg/galachain). We are a small team and this is an ambitious project. 
+
+GalaChain runs on [Hyperledger Fabric](https://www.lfdecentralizedtrust.org/projects/fabric). 
+
+A running network is generally comprised of many separate services: Peers, orderers, certicate authorities, etc. 
+
+As such, most development environments rely on [containerization](https://en.wikipedia.org/wiki/Containerization_(computing)) using [Docker](https://en.wikipedia.org/wiki/Docker_(software)). 
+
+Developers experienced with containers may choose to work directly with our [Docker image](#use-docker-image-linux-macos-or-windows) or via a VSCode [Dev Container](#using-dev-containers-linux-or-macos) as documented below. 
+
+Primarily, we offer detailed instructions for setting up a [Local Development Environment](#local-development-environment-linux-macos-or-windows-with-wsl) on various operating systems. 
+
+Additionally, our [Test Net Environment](./from-zero-to-deployment.md) is under active development. The public test net can provide a way for developers to get up and running without needing to run a local Hyperledger Fabric network at all. 
+
+* [Local Development Environment](#local-development-environment-linux-macos-or-windows-with-wsl)
+* [Test Net Environment Deployment](./from-zero-to-deployment.md)
+* [GalaChain Docker image](#use-docker-image-linux-macos-or-windows)
+* [Dev Container](#using-dev-containers-linux-or-macos)
+
+Common issues encountered during development environment setup are collected on our [Troubleshooting](./troubleshooting.md) page. 
 
-### Requirements
 
-You need to have the following tools installed on your machine:
+## Local Development Environment (Linux, MacOS, or Windows with WSL)
+
+### Prerequisite Requirements
+
+You will need to have the following tools installed on your machine:
 
 - Node.js 18+
 - Docker and Docker Compose
-- [jq](https://jqlang.github.io/jq/) and [yq](https://github.com/mikefarah/yq)
+- [jq](https://jqlang.github.io/jq/download/) and [yq](https://github.com/mikefarah/yq)
+
+#### Linux
+
+[Install Docker Engine](https://docs.docker.com/engine/install/) following the instructions for your preferred Linux Distribution.
+
+Follow the [Linux post-installation steps for Docker Engine](https://docs.docker.com/engine/install/linux-postinstall/).
+
+Install Node.js using [nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating), the Node Version Manager. After [verifying the installation](https://github.com/nvm-sh/nvm?tab=readme-ov-file#verify-installation), install Node.js v18 using:
+
+```bash
+nvm install 18
+```
+
+Follow the linked installation instructions to install [jq](https://jqlang.github.io/jq/download/) and [yq](https://github.com/mikefarah/yq) on your system.
+
+#### MacOS
+
+##### Containers on MacOS
+
+Consider using [homebrew](https://brew.sh/) to install and manage prerequisite software.
+
+GalaChain requires a Docker runtime to compose the underlying Hyperledger Fabric network. 
+
+Install [Docker Desktop](https://docs.docker.com/get-started/get-docker/), either using the provided graphical installer or via homebrew: 
+
+```bash
+brew install --cask --appdir="/Applications" docker`
+```
+
+If preferred, choose an alternative to Docker Desktop such as [colima](https://github.com/abiosoft/colima), [Orbstack](https://orbstack.dev/), a full Linux Virtual Machine ([instructions](#linux-virtual-machines-on-macos) below), or a direct command-line install of Docker Engine using a tool like homebrew. 
+
+Specifics for most of these options are currently outside the scope of this document, but one important note is that Colima's default limit of 2GB of memory on Docker's linux/arm64 VM is insufficient for a running GalaChain network. 
+
+It is important to be aware that running Docker on macOS always involves using a linux/arm64 Virtual Machine under the hood, with only the Docker CLI running natively within macOS. 
+
+Be advised that mixing virtualization technologies, such as running Docker Desktop or Colima while using Virtual Machines managed by UTM or VMware Fusion, can cause unpredictable problems. It's best to either go with a containerization option or full virtualization, not both. 
+
+Install Node.js using [nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating), the Node Version Manager. After [verifying the installation](https://github.com/nvm-sh/nvm?tab=readme-ov-file#verify-installation), install Node.js v18 using:
+
+```bash
+nvm install 18
+```
+
+Follow the linked installation instructions to install [jq](https://jqlang.github.io/jq/download/) and [yq](https://github.com/mikefarah/yq) on your system.
+
+##### Linux Virtual Machines on MacOS
+
+Rather than relying on tools like Docker Desktop or Colima to abstact away the details of the [Virtual Machine](https://en.wikipedia.org/wiki/Virtual_machine) used to emulate Linux on a MacOS host, you might prefer to simply run Docker in a dedicated Linux VM. 
+
+[UTM](https://docs.getutm.app/installation/macos/) is a virtual machine host for iOS and macOS based of QEMU. You can support the developers by installing it from the Mac App Store, download it for free from Github, or use [homebrew](https://formulae.brew.sh/cask/utm). 
+
+While UTM can emulate a different CPU architecture than present on the host for guest operating systems, performance will be significantly improved if the Host and Guest CPU architectures match: i.e. ARM64 Linux for Apple Silicon hosts, and x86_64 Linux for Intel Macs. 
+
+UTM provides [guides](https://docs.getutm.app/guides/guides/) for installing several different guest operating systems using their software. 
+
+For GalaChain development, we recommend using a Linux ARM64 image when working on an Apple Silicon Mac. ARM64 images are currently available for Debian, Ubuntu, or Fedora. Intel Macs can use x86_64 Linux Virtual Machines.
+
+Once a guest operating system is up and running, follow the [`Linux`](#linux) instructions above to setup prerequisite software within your guest environment. 
+
+An important consideration when using a Linux ARM64 Virtual Machine concerns the available OS/Arch builds of Docker images downloadable through Docker Hub and other container registries. 
+
+This is slowly becoming a non-issue, but there may be times where you see an error message such as:
+
+```
+WARNING: The requested image's platform (linux/amd64) does not match the
+ detected host platform (linux/arm64/v8) and no specific platform 
+ was requested.
+```
+
+This occurs when an Docker image is provided for the linux/amd64 architecture, but not the linux/arm64 architecture. An example would be the Hyperledger Fabric Certificate Authority (fabric-ca) image for version 1.5.5. 
+
+Advanced users can work around these issues by manually building their own image locally compiled to their specific architecture.
+
+
+#### Windows
+
+Microsoft offers the [Windows Sub System for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/about) which greatly faciliates web application and cross-platform development on Microsoft Windows 10 and 11. 
+
+Install [Docker Desktop](https://docs.docker.com/get-started/get-docker/).
+
+> If you are using Windows with WSL don't forget to enable integration with WSL on Docker Desktop.
+
+And see [How to use Windows with WSL](./windows-wsl.md) in order to get up and running for local GalaChain development. 
+
+Similar to how it is detailed above in the [MacOS](#macos) section, virtualization is an alternative to WSL on Windows hosts. 
+
+Interested users can check out Microsoft's [introduction to Hyper-V](https://learn.microsoft.com/en-us/virtualization/hyper-v-on-windows/about/) or explore third party offerings that enable Linux operating system virtualization on Windows. 
+
 
 ### 1. Install our CLI
 
@@ -71,7 +181,7 @@ Navigate to [http://localhost:3010/graphiql](http://localhost:3010/graphiql) to
 
 ---
 
-## Option 2: Use Docker image (Linux, MacOS or Windows)
+## Use Docker image (Linux, MacOS or Windows)
 
 ### Requirements
 
@@ -127,7 +237,7 @@ Navigate to [http://localhost:3010/graphiql](http://localhost:3010/graphiql) to
 
 ---
 
-## Option 3: Using Dev Containers (Linux or MacOS)
+## Using Dev Containers (Linux or MacOS)
 
 ### Requirements
 
@@ -203,43 +313,3 @@ Navigate to [http://localhost:3010/graphiql](http://localhost:3010/graphiql) to
 
 ---
 
-# Troubleshooting
-
-## Docker Desktop on Windows
-
-#### If you are using Windows with WSL don't forget to enable integration with WSL on Docker Desktop.
-```
-Docker Desktop > Settins > Resources > WSL Integration
-```
-
-#### Docker: image operating system "linux" cannot be used on this platform: operating system is not supported.
-
-Some versions of the Docker Desktop for Windows have a bug that prevents the use of Linux images. If you are facing this issue, you can use the WSL2 backend to run Docker. To do so, go to Docker Desktop > Settings > General and select WSL2 as the default backend.
-
-#### Docker: "no matching manifest for windows/amd64 in the manifest list entries".
-
-To bypass this issue you can run the Docker daemon in experimental mode:
-
-```
-Docker Desktop > Settins > Docker Engine > Edit the Docker daemon file > Set the "experimental": true > Apply & Restart
-```
-
-## Docker
-
-#### Docker: Error response from daemon: Conflict. The container name "/<container_name>" is already in use by container "<container_id>". 
-
-You have to remove (or rename) that container to be able to reuse that name.
-
-## WSL
-
-#### ./fablo-target/fabric-config/configtx.yaml: no such file or directory
-
-Make sure you are running it as a administrator of the cmd or powershell.
-
-#### docker: Got permission denied
-
-If you get a `docker: Got permission denied` error when running npm run network:start or npm run network:up, you may need to enable the configuration:
- ```
-Docker Desktop > Settins > General > Expose daemon on tcp://localhost:2375 without TLS
-```
-If it still doesn't work, you can try use the WSL Ubuntu-20.04 distribution to run the network.
diff --git a/docs/index.md b/docs/index.md
@@ -1,7 +1,7 @@
 # GalaChain SDK
 
 Welcome to developing with GalaChain!
-GalaChain is a layer 1 blockchain designed to be the foundation of Web3 Gaming, Entertainment and more.
+GalaChain is a Layer 1 (L1) Blockchain designed to be the foundation of Web3 Gaming, Entertainment and more.
 
 ## Features
 
@@ -31,7 +31,3 @@ Read more about [GalaChain](galachain.md).
 - [`chain-client`](chain-client-docs/exports.md) - GalaChain client library
 - [`chain-test`](chain-test-docs/exports.md) - Unit testing and integration testing for GalaChain
 - [`chaincode` framework](chaincode-docs/exports.md) - Framework for building chaincodes on GalaChain
-
-## Documentation in PDF format
-
-- [PDF file](./pdf/sdk-documentation.pdf)
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -0,0 +1,40 @@
+# Troubleshooting
+
+## Docker Desktop on Windows
+
+#### If you are using Windows with WSL don't forget to enable integration with WSL on Docker Desktop.
+```
+Docker Desktop > Settins > Resources > WSL Integration
+```
+
+#### Docker: image operating system "linux" cannot be used on this platform: operating system is not supported.
+
+Some versions of the Docker Desktop for Windows have a bug that prevents the use of Linux images. If you are facing this issue, you can use the WSL2 backend to run Docker. To do so, go to Docker Desktop > Settings > General and select WSL2 as the default backend.
+
+#### Docker: "no matching manifest for windows/amd64 in the manifest list entries".
+
+To bypass this issue you can run the Docker daemon in experimental mode:
+
+```
+Docker Desktop > Settins > Docker Engine > Edit the Docker daemon file > Set the "experimental": true > Apply & Restart
+```
+
+## Docker
+
+#### Docker: Error response from daemon: Conflict. The container name "/<container_name>" is already in use by container "<container_id>". 
+
+You have to remove (or rename) that container to be able to reuse that name.
+
+## WSL
+
+#### ./fablo-target/fabric-config/configtx.yaml: no such file or directory
+
+Make sure you are running it as a administrator of the cmd or powershell.
+
+#### docker: Got permission denied
+
+If you get a `docker: Got permission denied` error when running npm run network:start or npm run network:up, you may need to enable the configuration:
+ ```
+Docker Desktop > Settins > General > Expose daemon on tcp://localhost:2375 without TLS
+```
+If it still doesn't work, you can try use the WSL Ubuntu-20.04 distribution to run the network.