diff --git a/.travis.yml b/.travis.yml
index 127223872..f0d84e72a 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -1,26 +1,25 @@
 language: c # or other C/C++ variants
 
-# https://docs.travis-ci.com/user/caching/#ccache-cache
+# https://docs.travis-ci.com/user/caching/
 cache:
-  ccache: true
   directories:
-    - rocksdb-5.14.2
     - nim
+    - rocksdb
 
 install:
   # build nim from our own branch, to avoid downtime due to nim regressions
-  # Should work for both osx and linux..
-  - "export NPROC=$(python -c 'import multiprocessing as mp; print(mp.cpu_count())')"
-  - export NIMVER=$(git ls-remote https://github.com/status-im/nim.git HEAD | cut -f 1)
+  - "export NIMVER=$(git ls-remote https://github.com/status-im/nim.git HEAD | cut -f 1)"
   - "{ [ -f nim/$NIMVER/bin/nim ] && [ -f nim/$NIMVER/bin/nimble ] ; } || { rm -rf nim ; mkdir -p nim; git clone https://github.com/status-im/nim.git nim/$NIMVER; cd nim/$NIMVER; sh build_all.sh; cd ../.. ; }"
-  - export PATH=$PWD/nim/$NIMVER/bin:$PATH
+  - "export PATH=$PWD/nim/$NIMVER/bin:$PATH"
+
   # build our own rocksdb to test with a fixed version that we think works
-  - "[ -f rocksdb-5.14.2/Makefile ] || { wget https://github.com/facebook/rocksdb/archive/v5.14.2.tar.gz && tar xvf v5.14.2.tar.gz; }"
-  - cd rocksdb-5.14.2
+  - "export ROCKSDBVER=5.14.2"
+  - "[ -f rocksdb/rocksdb-$ROCKSDBVER/Makefile ] || { rm -rf rocksdb ; mkdir -p rocksdb; cd rocksdb; wget https://github.com/facebook/rocksdb/archive/v$ROCKSDBVER.tar.gz && tar xvf v$ROCKSDBVER.tar.gz; cd ..; }"
+  - cd rocksdb/rocksdb-$ROCKSDBVER
   - "[ -f util/build_version.cc ] || { make util/build_version.cc ; }" # use cached version if possible
   - export NO_UPDATE_BUILD_VERSION=1
   - make shared_lib -j$NPROC && sudo make install-shared
-  - cd ..
+  - cd ../..
 
 script:
   - nimble install -dy && nimble test
@@ -33,12 +32,9 @@ matrix:
     - os: linux
       sudo: required
       before_install:
-        - sudo apt-get install -y libssl-dev libgflags-dev libsnappy-dev
         - export INSTALL_PATH=/usr
+        - export NPROC=$(nproc)
     - os: osx
       before_install:
-        # - brew update
-        - brew install snappy ccache
-        - export PATH="/usr/local/opt/ccache/libexec:$PATH"
         - export INSTALL_PATH=$HOME # included in DYLD_FALLBACK_LIBRARY_PATH
-        # - brew install gcc
+        - export NPROC=$(sysctl -n hw.ncpu)
diff --git a/README.md b/README.md
index 671425089..0a86f8400 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,7 @@
 ![Stability: experimental](https://img.shields.io/badge/stability-experimental-orange.svg)
 
 Join the Status community chats:
+[![Gitter: #status-im/nimbus](https://img.shields.io/badge/gitter-status--im%2Fnimbus-orange.svg)](https://gitter.im/status-im/nimbus)
 [![Riot: #dev-status](https://img.shields.io/badge/riot-%23dev--status%3Astatus.im-orange.svg)](https://chat.status.im/#/room/#dev-status:status.im)
 [![Riot: #nimbus](https://img.shields.io/badge/riot-%23nimbus%3Astatus.im-orange.svg)](https://chat.status.im/#/room/#nimbus:status.im)
 
@@ -17,11 +18,12 @@ Join the Status community chats:
 
 ### Prerequisites
 
-Please install a recent version of Facebook's RocksDB following the instructions here:
-
-https://github.com/facebook/rocksdb/blob/master/INSTALL.md
-
-Currently Nimbus requires the latest development version of the Nim programming language. Follow the [installation steps](https://github.com/nim-lang/Nim) or use [choosenim](https://github.com/dom96/choosenim).
+* A recent version of Nim
+  * We use the version in the [Status fork](https://github.com/status-im/Nim)
+  * Normally, this is the latest released version of Nim but it may also include custom patches
+  * Follow the Nim installation instructions or use [choosenim](https://github.com/dom96/choosenim) to manage your Nim versions
+* A recent version of Facebook's [RocksDB](https://github.com/facebook/rocksdb/)
+  * Compile [from source](https://github.com/facebook/rocksdb/blob/master/INSTALL.md) or use the package manager of your OS
 
 ### Obtaining the prerequisites through the Nix package manager
 
@@ -33,19 +35,40 @@ nix-shell nimbus.nix
 
 ### Build
 
-You can build the package and run the tests using `nimble test`. You can run the example using `nim compile --run examples/decompile_smart_contract.nim`.
+We use [Nimble](https://github.com/nim-lang/nimble) to manage dependencies and run tests.
 
-You can run the official Ethereum JSON tests for the EVM this way:
-
-create a `./build` directory with `mkdir build` in your cloned repository.
-
-Run
-
-```
-nim c -r --nimcache:nimcache -o:build/test tests/test_vm_json.nim
+To build and run test suite:
+```bash
+nimble test
 ```
 
-The executable will be put in `build`, and nim compilation cache will use `nimcache`.
+Based on our config, Nimble will write binaries to `build/` - you can do this manually also, as in the following examples:
+
+Run example:
+```bash
+mkdir -p build
+nim c -o:build/decompile_smart_contract -r examples/decompile_smart_contract.nim
+```
+
+Run Ethereum [JSON-based VM tests](https://github.com/ethereum/tests/):
+```
+mkdir -p build
+nim c -o:build/test_vm_json -r tests/test_vm_json.nim
+```
+
+#### Troubleshooting
+
+Sometimes, the build will fail even though the latest CI is green - here are a few tips to handle this:
+
+* Wrong Nim version
+  * We depend on many bleeding-edge features - Nim regressions often happen
+  * Use the [Status fork](https://github.com/status-im/Nim) of Nim
+* Wrong versions of dependencies
+  * nimble dependency tracking often breaks due to its global registry
+  * wipe the nimble folder and try again
+* C compile or link fails
+  * Nim compile cache is pretty buggy and sometimes will fail to recompile
+  * wipe your nimcache folder
 
 ## License