From 062a348e556e351a9f93b9e76ed8db8837e9bd18 Mon Sep 17 00:00:00 2001
From: Stanislav Bezkorovainyi <stanislavbezkor@gmail.com>
Date: Tue, 15 Dec 2020 11:45:58 +0200
Subject: [PATCH] Add some troubleshooting cases and correct versioning

---
 docs/development.md           |  6 +++--
 docs/launch.md                | 33 +++++++++++++++++++++++++
 docs/setup-dev.md             | 45 +++++++++++++++++++++++++++++++++--
 infrastructure/zk/src/init.ts |  4 ++--
 4 files changed, 82 insertions(+), 6 deletions(-)

diff --git a/docs/development.md b/docs/development.md
index bc5da0d6ed..479a465db4 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -135,7 +135,7 @@ zk test db
 - Running the `rust` unit-tests (heavy tests such as ones for `circuit` and database will not be run):
 
   ```sh
-  f cargo test
+  zk f cargo test
   ```
 
 - Running the database tests:
@@ -167,7 +167,7 @@ zk test db
 - Running the benchmarks:
 
   ```sh
-  f cargo bench
+  zk f cargo bench
   ```
 
 - Running the loadtest:
@@ -178,6 +178,8 @@ zk test db
   zk run loadtest # Has to be run in the 3rd terminal
   ```
 
+  **Note**. If you have compilation issues with `sqlx`, then make sure to run `zk up` before running the tests.
+
 ## Developing circuit
 
 - To generate proofs one must have the universal setup files (which are downloaded during the first initialization).
diff --git a/docs/launch.md b/docs/launch.md
index 56b6952792..65ee4b16fe 100644
--- a/docs/launch.md
+++ b/docs/launch.md
@@ -18,6 +18,8 @@ zk init
 During the first initialization you have to download around 8 GB of setup files, this should be done once. If you have a
 problem on this step of the initialization, see help for the `zk run plonk-setup` command.
 
+If you any other problems with the `zk init` command, go to the `Troubleshooting` section at the end of this file. There are solutions for some common error cases.
+
 To completely reset the dev environment:
 
 - Stop services:
@@ -87,3 +89,34 @@ zk prover
 
 Make sure you have environment variables set right, you can check it by running: `zk env`. You should see `* dev` in
 output.
+
+## Troubleshooting
+
+### Invalid mount config for type "bind"
+**Problem.** `zk init` failes with the following error:
+```sh
+Cannot create container for service geth: invalid mount config for type "bind": bind source path does not exist: /home/stanislav/matter-labs/zksync-dev/volumes/geth
+``` 
+
+You might also see these errors not only for geth, but also for `postgres` and `tesseracts`.
+
+**Solution**. In the repository folder there should be a folder `volumes`, with three folders inside of it: `geth`, `tesseracts`, `postgres`. If some of these are missing, you must create them on your own.
+
+### SSL error: certificate verify failed
+
+**Problem**. `zk init` failes with the following error:
+```sh
+Initializing download: https://universal-setup.ams3.digitaloceanspaces.com/setup_2%5E20.key
+SSL error: certificate verify failed
+```
+
+**Solution**. Make sure that the version of `axel` on your computer is `2.17.10`.
+
+### rmSync is not a function
+
+**Problem**. `zk init` failes with the following error:
+```sh
+fs_1.default.rmSync is not a function
+```
+
+**Solution**. Make sure that the version of `node.js` installed on your computer is `14.14.0` or higher.
diff --git a/docs/setup-dev.md b/docs/setup-dev.md
index bccf82f3a0..7b4a0e443f 100644
--- a/docs/setup-dev.md
+++ b/docs/setup-dev.md
@@ -32,12 +32,23 @@ sudo usermod -a -G docker your_user_name
 After that, you should logout and login again (user groups are refreshed after the login). The problem should be solved
 at this step.
 
+If logging out does not help, restarting the computer should.
+
 ## `Node` & `Yarn`
 
-1. Install `Node` (requires version 14.13.1 or higher).
+1. Install `node` (requires version 14.14.0 or higher).
+Since our team tries to always use the latest LTS version of `node.js`, we suggest you to install [nvm](https://github.com/nvm-sh/nvm). It will allow you to update the node version quickly in the future.
 
 2. Install `yarn`. Instructions can be found on the [official site](https://classic.yarnpkg.com/en/docs/install/).
 
+Check if yarn is installed by running the following command:
+
+```sh
+$ yarn -v
+```
+
+If you face any problems when installing `yarn`, it might be the case that your package manager installed the wrong package. Make sure to thoroughly follow the instructions above on the official website. It has a lot of troubleshooting guides in it. 
+
 3. Run `yarn global add @vue/cli-service`
 
 ## `Axel`
@@ -56,6 +67,14 @@ On debian-based linux:
 sudo apt-get install axel
 ```
 
+Check the version of `axel` with the following command:
+
+```sh
+axel --version
+```
+
+Make sure the version is `2.17.10`.
+
 ## `Rust`
 
 Install the latest `rust` version.
@@ -66,7 +85,7 @@ Verify the `rust` installation:
 
 ```
 rustc --version
-rustc 1.41.0 (5e1a79984 2020-01-27)
+rustc 1.48.0 (7eac88abb 2020-11-16)
 ```
 
 ### `lld`
@@ -110,6 +129,12 @@ On debian-based linux:
 sudo apt-get install libpq-dev
 ```
 
+If you still see the errors, install the `build-essential` package. On debian-based linux:
+
+```sh
+sudo apt install build-essential
+```
+
 ## `sqlx` CLI
 
 Also, we need [`sqlx`](https://github.com/launchbadge/sqlx) CLI (it is used to generate database wrappers):
@@ -118,6 +143,22 @@ Also, we need [`sqlx`](https://github.com/launchbadge/sqlx) CLI (it is used to g
 cargo install --version=0.2.0 sqlx-cli
 ```
 
+If you face an error `Could not find directory of OpenSSL installation`, then you should do the following. The instruction is targeted on debian-based Linux, but generally the steps are similar for all OS.
+
+- Install `libssl-dev`:
+```sh
+sudo apt install libssl-dev
+```
+- Install OpenSSL. Here is [the instruction for Ubuntu](https://www.notion.so/matterlabs/Setup-checklist-056a2e5c3a104608a5a25788520ef0ff#5f34729bdffe496f9d38c46787c640d7), but the steps should be similar for the debian-based Linux distros.
+- Add `OPENSSL_DIR` variable to your environment. This would typically be `/usr/local/ssl`. You can do this by adding the following line to your shell profile file (e.g. `~/.bash_profile`):
+```sh
+export OPENSSL_DIR=/usr/local/ssl
+```
+- Install `package-config`:
+```sh
+sudo apt-get install -y pkg-config
+```
+
 ## `solc`
 
 You have to install `solc` v0.5.16. Instructions can be found at
diff --git a/infrastructure/zk/src/init.ts b/infrastructure/zk/src/init.ts
index 8b54b7a67a..04126f4ec9 100644
--- a/infrastructure/zk/src/init.ts
+++ b/infrastructure/zk/src/init.ts
@@ -33,8 +33,8 @@ async function checkEnv() {
     }
     await utils.exec('cargo sqlx --version');
     const { stdout: version } = await utils.exec('node --version');
-    if ('v14' >= version) {
-        throw new Error('Error, node.js version 14 or higher is required');
+    if ('v14.14' >= version) {
+        throw new Error('Error, node.js version 14.14.0 or higher is required');
     }
 }