Updates home setup instructions

README.md

@@ -5,10 +5,11 @@ Hit the ground running with Codex.
 This [disclaimer](./DISCLAIMER.md) applies to everything found in this repository. Be sure to read it.
 
 ## Home Setup
-Want to try Codex? You can run it on your own hardware and from your home network. Join our public dev-net. Start [here](./SETUP_HOME.md)
+Want to join the Codex Testnet? You can run it on your own hardware and from your home network. Join our public testnet. Start [here](./SETUP_HOME.md)
 
 ### Links
  - Codex Website - [codex.storage](https://codex.storage)
+ - Docs - [docs.codex.storage](https://docs.codex.storage)
  - Codex Whitepaper - [codex.storage](https://codex.storage)
  - Codex API - [api.codex.storage](https://api.codex.storage)
  - Codex Discord - [discord.gg/codex-storage](https://discord.gg/codex-storage)

SETUP_HOME.md

@@ -1,5 +1,5 @@
 # Home Setup
-With these instructions you can set up a Codex node on your machine at home. If you run into trouble, reach out via our Discord server: https://discord.gg/codex-storage
+With these instructions you can set up a Codex node on your machine at home. If you run into trouble, try the [docs](https://docs.codex.storage) or reach out via our Discord server: https://discord.gg/codex-storage
 
 ## Prerequisites for Home Setup
 In order for Codex to work from your home machine, please make sure you know your public IP address and are able to forward ports on your router or modem. If you're planning to participate as a storage node, please keep in mind that storage nodes are expected to maintain uptime as soon as they are engaged in one or more storage contracts. Taking your storage node offline while it's hosting storage contracts may result in loss of tokens.
@@ -7,6 +7,9 @@ In order for Codex to work from your home machine, please make sure you know you
 ## Disclaimer
 This [disclaimer](./DISCLAIMER.md) applies to everything found in this repository. Be sure to read it.
 
+## Running Codex
+This document assumes you have Codex installed and are able to run it. You can obtain Codex by building from sources, downloading binaries, or using a docker image. Need to install Codex? Go [here](https://docs.codex.storage).
+
 ## Port Forwarding
 Codex requires you to forward two ports: One for data exchange, and one for discovery. These ports can be configured with the CLI parameters `--listen-addrs` and `--disc-port`. We proceed with 8070 for the listen port, and 8090 for the discovery port.
 
@@ -14,6 +17,9 @@ Codex requires you to forward two ports: One for data exchange, and one for disc
 - LAN port: 8070 - Public port: 8070 - Protocol: TCP
 - LAN port: 8090 - Public port: 8090 - Protocol: UDP
 
+> 📢 Running Codex from Docker?
+> Be sure to expose the above ports and protocols in your docker-compose file. Additionally, some users have reported connection issues on some platforms. We recommend using docker's `bridge network` driver for the Codex container.
+
 ## Public IP Address
 It is important that your Codex node can be reached by others in the network. For this reason, Codex will announce your public IP address to the network. If the announced address is incorrect, other nodes will not be able to establish connections with yours. Here is a list of common issues and possible solutions.
 
@@ -21,37 +27,16 @@ It is important that your Codex node can be reached by others in the network. Fo
 Many ISPs (especially mobile carriers) are using a sub-NAT. In this setup, the IP address your modem receives as public address is not actually exposed to the internet. Rather it is another sub-net that is connected to the internet through another NAT. You can detect this issue by accessing your modem's admin interface and finding the reported public IP address. If it does not match with the IP address provided by services like whatsmyip.org, then you might be behind a sub-NAT. A possible solution: Contact your ISP and ask them to provide you a dynamic internet IP address. Many ISPs can switch you over with the push of a button.
 
 - 2. VPNs<br>
-We're all fans of privacy here, but if your uplink is routed through a VPN service, it is unlikely that you're able to get the forwarding working correctly. Some VPNs may try to block traffic that looks peer-to-peer. A solution is to not run a VPN on, or exampt from your VPN network the local device on which you're planning to run Codex.
+We're all fans of privacy here, but if your uplink is routed through a VPN service, it is unlikely that you're able to get the forwarding working correctly. Some VPNs may try to block traffic that looks peer-to-peer. A solution is to not run a VPN, or exampt from your VPN network the local device on which you're planning to run Codex.
 
 - 3. Good old firewalls<br>
 It still happens that your system's default security settings prevent Codex from accepting connections coming from outside the local address space. Please make sure it's configured properly.
 
 **Discover your public IP address and keep it handy** (https://www.whatsmyip.org)
 
-## Codex Setup
+## Generate an ETH key-pair
+Codex uses an Eth address (hot wallet) to transact with other nodes in the network. We will need a file containing only a private key, and we'll need the corresponding address. You can generate them using your own preferred method. For convenience, this repository contains a script, `/scripts/generate.sh` which you can use to generate a key pair. *Keys generated with this script should be used for testing purposes only and should be considered insecure.*
 
-### 1. Clone this repository
-```
-git clone https://github.com/codex-storage/codex-testnet-starter.git
-cd codex-testnet-starter/scripts
-```
-> #### 📢 **Windows users**<br>
->If you are using a native Windows environment, and not a *nix-like environment
->(eg CYGWIN/MINGW/MSYS/MINGW), use the `scripts/windows` directory.
-
-### 2. Build or Download Codex
-> 📢 If you're planning to run a storage node, additional steps are required.
-
-To build Codex from sources, follow the instructions [here](https://github.com/codex-storage/nim-codex/blob/master/BUILDING.md)
-> For storage nodes, be sure to build Codex from the branch `feature/ceremony-files`
-
-To download Codex binaries, run `download_online` script.
-> For storage nodes, modify the download script first by enabling it to download the 'prover' version of the binary. Look for the variable `BINARY_NAMES`.
-```shell
-./download_online.sh
-```
-
-### 3. Generate an ETH key-pair
 Run `generate` script:
 ```shell
 ./generate.sh
@@ -59,43 +44,74 @@ Run `generate` script:
  * Your private key will be saved to scripts/eth.key.
  * Your ethereum address will be saved to scripts/eth.address.
 
-> #### 📢 **Don't lose your keys**<br>
+**Generate a key pair**
->If you lose your key and address, you can generate new ones. But the faucet and/or discord bot may refuse to give you new tokens for quite a while!
 
-### 4. Start Codex node
+## Start Codex node
-Modify the run script: Comment out the Local network SPR. Comment in the Cloud-Node-01 SPR.
+We're now ready to start your Codex node and join the testnet!
-Set your public IP and run the `run_client` script. 
+Several configuration options must be set correctly, so the node knows how to connect into the testnet. You can review all of Codex's options with `./codex --help`. Each option can be set via CLI argument, or matching environment variable. (For example, option `--api-port` can also be set with env-var `CODEX_API_PORT`.) We recommend you give the list of options a quick read.
-```shell
+
-LOCALIP=<PUBLIC-IP-HERE> ./run_client.sh
+> Thinking of building a shell script? Start here and modify [this](./scripts/run_testnet.sh).
-```
+
-> 📢 For storage nodes, modify the run script first by adding the `prover` argument:
+These options are required to join the testnet:
-```bash
+ - `--bootstrap-node=SPR` - Set SPR to one of the Codex Testnet bootstrap node SPRs found [here](https://docs.codex.storage/networks/testnet)
-  ...
+ - `--nat=IP` - Set IP to your public IP address.
-  --bootstrap-node=${BOOTSPR} \
+ - `--listen-addrs=ADDR` - Set ADDR to "/ip4/0.0.0.0/tcp/8070". Note: If you changed the TCP port in the port forwarding step previously, change it here as well.
-  persistence \
+ - `--disc-port=PORT` - Set PORT to 8090. Again: If you changed it in the forward, do the same thing here.
-  --eth-private-key=eth.key \
+ - `persistence` - Tells the node we want to enable marketplace interactions.
-  --eth-provider=https://rpc.testnet.codex.storage \
+ - `--eth-private-key=FILE` - Set FILE to your private key file.
-  --marketplace-address=0x9C88D67c7C745D2F0A4E411c18A6a22c15b37EaA \
+ - `--eth-provider=URL` - Set URL to the "Geth Public RPC" found [here](https://docs.codex.storage/networks/testnet)
-  prover
+ - `--marketplace-address=ADDR` - Set ADDR to `0xB119d28d3A1bFD281b23A0890B4c1B626EE8F6F0`
-```
+
+The above options allow you to join the testnet, exchange data, and purchase storage in the network. If you wish to *sell storage space* to the network, you must include one additional argument:
+ - `prover` - Tells the node we want to enable storage space selling
+
+> You should know: Selling storage space required a zero-knowledge circuit in order to generate storage proofs. On first start, Codex will prompt you to download the correct circuit files. Additionally, proof generation has higher CPU and RAM requirements than other node operations.
+
+> 📢 Are you using docker environment-variables to configure Codex?
+> Options `persistence` and `prover` have no equivalent env-var. (Known issue in config-option-handling library.) To provide these arguments to Codex, you must override the container's command. Example:
+> ```
+>     command:
+>      - bash
+>      - /docker-entrypoint.sh
+>      - persistence
+>      - prover
+> ```
+> 📢 When running in a container, option `--eth-private-key` can't be set to a key file outside of your container. To solve this, set the environment variable `PRIV_KEY` to the content of your private key file. Scripting inside the docker container will automatically write this to a file in the container, set the correct permissions, and pass it to Codex.
+
+> 📢 Are you using Windows, and the "/" characters in the listen-addrs are giving you trouble?
+> In some shells, Windows will interpret "/" character as refering to "C:/" or the current working directory.
+> Our workaround is to convert the bash script to batch (.bat).
+
+> 📢 Are your eth private key file permissions insecure?
+> For Unix, use these steps:
+> 1. `chmod 600 "eth.key"`
+> For Windows, use these steps:
+> 1. Open explorer to the key file.
+> 2. Right-click it -> Properties.
+> 3. Security -> Advanced.
+> 4. Add -> Select a principal -> Advanced -> Find Now
+> 5. Select your user from the list -> OK -> OK
+> 6. Check 'Full control' -> OK
+> 7. Disable inheritance -> Remove all inheritance
+> 8. OK -> OK
 
 Unix users may be required to install libgomp:
 ```shell
 sudo apt-get install libgomp1
 ```
 
-### 5. Acquire tokens
+## Acquire tokens
-You can acquire tokens in one of two ways: the testnet faucets or the Discord bot.
+Your node will need some tokens to be able to both purchase storage space and host storage space. You can acquire tokens in one of two ways: the testnet faucets or the Discord bot.
 
 #### Faucets
-You will need both ETH and TST to use Codex:
+You will need both ETH and TST:
  1. Get some testnet ETH using https://faucet-eth.testnet.codex.storage.
  2. Get some testnet TST using https://faucet-tst.testnet.codex.storage.
 
 #### Discord bot
  - Join the Codex discord server: https://discord.gg/codex-storage.
  - Go to the "bot" channel, in the category "codex-bot".
- - Use `/set` command to enter your generated address.
+ - Use `/set` command to enter your eth address.
  - Use `/mint` command to receive some tokens.
 
 ### 6. Use Codex

scripts/run_testnet.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+set -e
+
+# Set variables
+DATA_DIR="data_client"
+ETHKEY="eth.key"
+BOOTSPR="spr:CiUIAhIhA7E4DEMer8nUOIUSaNPA4z6x0n9Xaknd28Cfw9S2-cCeEgIDARo8CicAJQgCEiEDsTgMQx6vydQ4hRJo08DjPrHSf1dqSd3bwJ_D1Lb5wJ4Qt_CesAYaCwoJBEDhWZORAnVYKkYwRAIgFNzhnftocLlVHJl1onuhbSUM7MysXPV6dawHAA0DZNsCIDRVu9gnPTH5UkcRXLtt7MLHCo4-DL-RCMyTcMxYBXL0"
+PUBLICIP=1.2.3.4
+
+mkdir -p ${DATA_DIR}
+chmod 0700 ${DATA_DIR}
+
+./codex \
+  --data-dir=${DATA_DIR} \
+  --storage-quota=11811160064 \
+  --nat=${PUBLICIP} \
+  --api-port=8080 \
+  --disc-port=8090 \
+  --listen-addrs=/ip4/0.0.0.0/tcp/8070 \
+  --bootstrap-node=${BOOTSPR} \
+  persistence \
+  --eth-private-key=${ETHKEY} \
+  --eth-provider=https://rpc.testnet.codex.storage \
+  --marketplace-address=0xB119d28d3A1bFD281b23A0890B4c1B626EE8F6F0