# Get Started ## System requirements To properly build components, you must have a system with the following requirements: * Linux (Ubuntu Preferred) Version: 20.04 or Above\ Mac(Apple Silicon or Intel) Version: Big Sur or Above\ Windows : Windows 10 or Above * 4 vCPU, 4 GB Memory at minimum * 4 GB of space minimum for zbox build components and storage allocation. ## Install zboxcli * [Linux Installation](#linux-installation) * [macOS Installation](#macos-installation) * [Windows Installation](#windows-installation) * [Building zboxcli from source](#building-zboxcli)[ ](https://docs.zus.network/guides/zbox-cli/get-started) ### Linux Installation 1. Download the latest linux zboxcli archive release from [here](https://github.com/0chain/zboxcli/releases/latest). 2. Open terminal and extract the downloaded archive to a specified directory using the command below. ``` tar -xzf zbox-linux.tar.gz --directory /usr/local/bin ``` 3. Provide execution privileges to the zbox executable. ``` chmod +x /usr/local/bin/zboxx ``` 4\. Navigate to the extracted directory path ``` cd /usr/local/bin ``` 5. Run the zbox executable type by using the command below. ``` ./zbox ``` On successful installation you will see a help section similar to response below: ``` zbox is a decentralized storage application written on the 0Chain platform. Usage: zbox [command] Available Commands: add Adds free storage assigner alloc-cancel Cancel an allocation ``` 6\. [Configure zbox network](#configure-zbox-network) 7\. .[Create a Storage Allocation](#creating-a-storage-allocation) ### Windows Installation 1. Download the latest windows zboxcli archive release from [here](https://github.com/0chain/zboxcli/releases/latest). 2. Extract the executable from the archive `zbox-windows.zip` 3. Now run the executable `zbox.exe` in windows command prompt. 4. On successful installation, you will see a help section similar to response below : ``` zbox is a decentralized storage application written on the 0Chain platform. Usage: zbox [command] Available Commands: add Adds free storage assigner alloc-cancel Cancel an allocation alloc-fini Finalize an expired allocation ``` 5\. [Configure zbox network](#configure-zbox-network) 6\. [Create a Storage Allocation](#creating-a-storage-allocation) ### macOS Installation 1. Download the latest mac zboxcli archive release from [here](https://github.com/0chain/zboxcli/releases/latest). 2. Open terminal and extract the downloaded archive to a specified directory using the commands below: ``` tar -xzf zbox-macos.tar.gz --directory /usr/local/bin ``` 3\. Provide execution privleges to the zbox executable. ``` chmod +x /usr/local/bin/zbox ``` 4. Navigate to extracted directory path . ``` cd /usr/local/bin ``` 5. Run the zbox executable using the command below. ``` ./zbox ``` On successful installation you will see a help section : ``` zbox is a decentralized storage application written on the 0Chain platform. Complete documentation is available at https://docs.0chain.net/0chain/ Usage: zbox [command] Available Commands: add Adds free storage assigner alloc-cancel Cancel an allocation alloc-fini Finalize an expired allocation ``` 6\. [Configure zbox network](#configure-zbox-network) 7\. [Create a Storage Allocation](#creating-a-storage-allocation) ## Building zboxcli ### **Building zboxcli for Windows** Windows 64bit (tested with Windows 11) 1. Installing msys2 from [here](https://github.com/msys2/msys2-installer/releases/download/2023-05-26/msys2-x86_64-20230526.exe). 2. Open MSYS2 MINGW64 shell from the windows start menu. The MINGW64 shell window should look similar to screenshot below.
3. Install the following libraries: ``` pacman -S base-devel git gcc make ``` 4. Install clang, go for mingw64 and unzip ``` pacman -S mingw-w64-x86_64-clang mingw-w64-x86_64-go unzip ``` **Note:** Restart mingw64 shell for Go to make changes. 5. Set environment variables ``` export GOROOT=/mingw64/lib/go export GOPATH=/mingw64 export PATH=$PATH:$GOROOT/bin # use clang as a default compiler for CGO go env -w "CC=/mingw64/bin/clang.exe" ``` 6. Clone zboxcli ``` git clone https://github.com/0chain/zboxcli.git ``` 7. Navigate to zboxcli directory and run the following command : ``` cd zboxcli make install ``` 8. Download necessary dll files as zip from [here](https://github.com/0chain/zboxcli/files/11840033/windows.dll.s.zip). 9. Unzip and copy dll's to zboxcli directory. The zboxcli directory will be available at the following path `C:\msys64\home\\zboxcli` if cloned under mingw64 shell. 10. Now run the `./zbox` command under zboxcli directory ``` ./zbox ``` On a successful build you will see a help section. 11\. [Configure zbox network](#configure-zbox-network) 12\. [Create a Storage Allocation](#creating-a-storage-allocation) ### Building zboxcli for Mac and Linux #### 1. Go Binaries Installation instructions for Mac and Linux can be found[ here](https://go.dev/doc/install). #### 2. Build-Essential(Only required for linux) The build essential package is required to build and make the zbox application. It includes the necessary GCC/g++ compilers and other essential critical libraries and utilities. Run apt update command to update the packages ``` sudo apt update ``` Get build-essential package ``` sudo apt-get install build-essential ``` 3. Clone the zboxcli repository using the command ``` git clone https://github.com/0chain/zboxcli.git ``` 4. Navigate into zboxcli directory using ``` cd zboxcli ``` 5. Use the make install command to compile the source code . ``` make install ``` This might take a minute. Here is a sample response of successful make install command: ![](https://979598987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNrAZJ0KGiwEbKkbVRYPu%2Fuploads%2Fgit-blob-4a1fc6c5e0d3419b507f6929ee253f0f9c31bb6d%2Fmake%20install.gif?alt=media) 6. Start the Zbox by navigating back to the zboxcli directory usingcd zboxcli\ and type ``` ./zbox ``` On a successful build you will see a help section. 7\. [Configure zbox network](#configure-zbox-network) 8\. [Create a Storage Allocation](#creating-a-storage-allocation) ## Configure Zbox network Configuration for the Züs network by default is stored in `network/config.yaml` file of the zbox github [repo](https://github.com/0chain/zboxcli) which we will copy to a new `config.yaml` file in our local system . 1. Make a new .zcn folder in the home directory of your system ``` mkdir $HOME/.zcn ``` **Note:** For windows create a folder named .zcn at \``C:\Users\`\`path.\ \ 2\. Copy[ config.yaml ](https://github.com/0chain/zboxcli/blob/staging/network/config.yaml)from zboxcli repo to `.zcn` directory ``` cp network/config.yaml $HOME/.zcn/config.yaml ``` 3. Open the `config.yaml` file located at `$HOME/.zcn` path of your system.The contents should be similar to the file below. ``` --- block_worker: https://demo.zus.network/dns signature_scheme: bls0chain min_submit: 50 min_confirmation: 50 confirmation_chain_length: 3 max_txn_query: 5 query_sleep_time: 5 # # OPTIONAL - Uncomment to use/ Add more if you want # preferred_blobbers: # - http://one.devnet-0chain.net:31051 # - http://one.devnet-0chain.net:31052 # - http://one.devnet-0chain.net:31053 ``` Zbox connects to the Züs network using the `block_worker` field. These network details are automatically fetched from the blockWorker's network API. Preferred Blobbers are also present which you can uncomment for using specified storage providers for handling your files. **Note:** In case you are configuring zbox network for [setting up blockchain locally](https://docs-old.zus.network/guides/setup-a-blockchain) the `block_worker` in config file above should be set to ## Creating a Storage Allocation The section assumes you have successfully build zbox. zbox provides a long list of components to use. Let's begin with the allocation of storage space on the 0Chain decentralized network. For creating a storage allocation using Zbox. You need to have a wallet with tokens available for performing allocations. 1. Create and get test tokens into your wallet using the zwallet CLI tool. If you have not installed zwallet CLI check instructions for [installation](https://docs-old.zus.network/zwallet-cli/get-started#install-zwalletcli) and [creating a wallet](https://docs-old.zus.network/zwallet-cli/get-started#creating-a-wallet) . 2. Once the wallet is created and has an available balance, you can create a storage allocation by using the Zbox `newallocation`command. To understand the syntax type ``` ./zbox newallocation --help ``` This will output the mandatory and optional flags that need to be added with the `newallocation`command. Here are the parameters : | Parameter | Description | Default | Valid Values | | ------------------ | --------------------------------------------------------- | -------------- | ------------ | | allocationFileName | local file to store allocation information | allocation.txt | file path | | cost | returns the cost of the allocation, no allocation created | | flag | | data | number of data shards, effects upload and download speeds | 2 | int | | expire | duration to allocation expiration | 720h | duration | | free\_storage | free storage marker file. | | file path | | owner | owner's id, use for funding an allocation for another | | string | | owner\_public\_key | public key, use for funding an allocation for another | | string | | lock | lock write pool with given number of tokens | | float | | mcct | max challenge completion time | 1h | duration | | parity | number of parity shards, effects availability | 2 | int | | read\_price | filter blobbers by read price range | 0-inf | range | | size | size of space reserved on blobbers | 2147483648 | bytes | | usd | give token value in USD | | flag | | write\_price | filter blobbers by write price range | 0-inf | range | 6. For getting started we can create a basic allocation with default types. This will only require essential specifiers such as `lock float`. We will add a float value of `0.5` which will lock 0.5 tokens with the allocation. The complete command for creating an allocation would be: ``` ./zbox newallocation --lock 0.5 ``` ​ Successful Response will create an allocation with allocation ID: ![](https://979598987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNrAZJ0KGiwEbKkbVRYPu%2Fuploads%2Fgit-blob-ab6884308e5b8f6dfa31ec4b28805e690a1b1f31%2Fzbox%20createallocation.gif?alt=media) If you are not able to create allocation and getting errors, check error causes [in TIps and Troubleshooting Section](#error-1-error-creating-allocation-transaction_not_found-transaction-was-not-found-on-any-of-the-sharders). 7\. Verify the allocation by using the command. ``` ./zbox listallocations ``` 9. Download necessary dll files as zip from [here](https://github.com/0chain/zboxcli/files/11840033/windows.dll.s.zip). 10. Unzip and copy dll's to zboxcli directory. The zboxcli directory will be available at the following path `C:\msys64\home\\zboxcli` if cloned under mingw64 shell. 11. Now run the `./zbox` command under zboxcli directory