2019-04-16 21:44:17 -07:00
|
|
|
# Zcash Docker Development Environment
|
|
|
|
|
2019-04-17 07:23:07 -07:00
|
|
|
🛑 **This is a work-in-progress and may not function reliably. It is certainly not
|
|
|
|
intended to be used in production.** 🛑
|
2019-04-16 21:57:31 -07:00
|
|
|
|
2019-04-16 21:44:17 -07:00
|
|
|
This repository contains a Dockerfile that will help you get started building
|
|
|
|
Zcash's mobile app wallet stack. The projects' code is kept on your host
|
|
|
|
filesystem and shared into the docker container, so you can keep using the
|
|
|
|
editors and tools you're familiar with, and only use the container to run
|
|
|
|
builds. You can also run the `zcashd` and `lightwalletd` services within the
|
|
|
|
container.
|
|
|
|
|
|
|
|
The development environment currently supports building:
|
|
|
|
|
|
|
|
- `zcashd`
|
|
|
|
- `librustzcash` (preview branch)
|
|
|
|
- `lightwalletd` (preview branch)
|
|
|
|
- `zcash-android-wallet-sdk` (preview branch)
|
|
|
|
- `zcash-android-wallet-poc`
|
|
|
|
|
|
|
|
## Quick Start
|
|
|
|
|
2019-04-23 15:17:32 -07:00
|
|
|
**Requirements:** Docker, KVM and a VNC client on the host (for the Android emulator), 30+GB free disk space.
|
2019-04-16 21:45:45 -07:00
|
|
|
|
2019-04-16 21:44:17 -07:00
|
|
|
First, checkout this repository:
|
|
|
|
|
|
|
|
```
|
|
|
|
git checkout <this-repository's-url>
|
|
|
|
cd zdev-docker
|
|
|
|
```
|
|
|
|
Next, build the Docker image. This will create an image called `zdev` which
|
|
|
|
has all of the build dependencies pre-installed:
|
|
|
|
|
|
|
|
```
|
|
|
|
docker build -t zdev docker
|
|
|
|
```
|
|
|
|
|
|
|
|
Now, clone all of the projects you want to work on into the `mount/` directory:
|
|
|
|
|
|
|
|
```
|
|
|
|
cd mount
|
|
|
|
git clone git@github.com:zcash/zcash.git
|
|
|
|
git clone git@github.com:zcash-hackworks/lightwalletd.git
|
|
|
|
git clone git@github.com:str4d/librustzcash.git --branch preview
|
|
|
|
git clone git@github.com:zcash/zcash-android-wallet-sdk.git --branch preview
|
2019-04-23 11:12:03 -07:00
|
|
|
git clone git@github.com:zcash/zcash-android-wallet-poc.git
|
2019-04-16 21:44:17 -07:00
|
|
|
cd ..
|
|
|
|
```
|
|
|
|
|
|
|
|
You can now launch a new container instance of `zdev` and have access to your
|
|
|
|
clones of `zcash`, `lightwalletd`, etc. from within:
|
|
|
|
|
|
|
|
```
|
2019-04-23 12:59:30 -07:00
|
|
|
docker run -it --mount type=bind,source="$(pwd)"/mount,target=/mount -p 5901:5901 --privileged zdev
|
2019-04-16 21:44:17 -07:00
|
|
|
```
|
|
|
|
|
|
|
|
The `./mount` directory will be shared between the host and the container,
|
|
|
|
accessible in the container at `/mount`. The changes you make to files inside
|
2019-04-23 12:59:30 -07:00
|
|
|
`/mount` in the container will change the files in `./mount`. The `-p 5901:5901
|
|
|
|
--privileged` arguments are optional; they are required for running and
|
|
|
|
connecting to the Android emulator inside the container.
|
2019-04-16 21:44:17 -07:00
|
|
|
|
2019-04-16 21:48:15 -07:00
|
|
|
The previous command opened a shell inside the container. You can run build
|
|
|
|
commands, for example:
|
2019-04-16 21:44:17 -07:00
|
|
|
|
|
|
|
```
|
|
|
|
cd /mount/zcash
|
|
|
|
./zcutil/build.sh -j$(nproc)
|
|
|
|
./qa/zcash/full-test-suite.py
|
|
|
|
```
|
|
|
|
|
|
|
|
See the individual projects' documentation for build instructions.
|
|
|
|
|
2019-04-16 21:48:15 -07:00
|
|
|
To open another shell into the running container, run `docker container ls`,
|
2019-04-17 07:21:30 -07:00
|
|
|
copy the container ID, and then run `docker exec -it <container ID> bash`. You
|
|
|
|
can start and stop the container with `docker start` and `docker stop`.
|
2019-04-16 21:44:17 -07:00
|
|
|
|
|
|
|
To update the Ubuntu packages in the `zdev` image or make changes to which
|
|
|
|
dependencies are installed, edit the `docker/install-build-dependencies.sh`
|
|
|
|
script and then re-build the `zdev` image using the same command as above. The
|
2019-04-17 07:21:30 -07:00
|
|
|
changes will take effect in the next *new* container instance you launch. You
|
|
|
|
can of course also just make changes directly to the container instead of
|
|
|
|
updating the image every time.
|
2019-04-16 21:44:17 -07:00
|
|
|
|
2019-04-16 21:48:15 -07:00
|
|
|
## Build Cheat Sheet
|
2019-04-16 21:44:17 -07:00
|
|
|
|
|
|
|
**Note:** All of the builds are independent for now, i.e. the build output of
|
|
|
|
`librustzcash` *doesn't* get used as an input to the `zcash-android-wallet-sdk`
|
|
|
|
build.
|
|
|
|
|
|
|
|
**`zcashd`**
|
|
|
|
|
|
|
|
```
|
|
|
|
cd /mount/zcash
|
|
|
|
./zcutil/build.sh -j$(nproc)
|
|
|
|
```
|
|
|
|
|
|
|
|
**`librustzcash`**
|
|
|
|
|
|
|
|
```
|
|
|
|
cd /mount/librustzcash
|
|
|
|
cargo build --release
|
|
|
|
```
|
|
|
|
|
|
|
|
**`lightwalletd`**
|
|
|
|
|
|
|
|
```
|
|
|
|
cd /mount/lightwalletd
|
2019-04-23 14:00:15 -07:00
|
|
|
go run cmd/ingest/main.go <...>
|
2019-04-16 21:44:17 -07:00
|
|
|
go run cmd/server/main.go <...>
|
|
|
|
```
|
|
|
|
|
|
|
|
**`zcash-android-wallet-sdk`**
|
|
|
|
|
|
|
|
```
|
|
|
|
cd /mount/zcash-android-wallet-sdk
|
|
|
|
./gradlew clean assembleZcashtestnetRelease
|
|
|
|
```
|
|
|
|
|
2019-04-23 11:12:03 -07:00
|
|
|
**`zcash-android-wallet-poc`**
|
|
|
|
|
2019-04-23 11:18:13 -07:00
|
|
|
First, generate a `google-services.json` file from [Google
|
|
|
|
Firebase](https://firebase.google.com/) and put it in
|
|
|
|
`zcash-android-wallet-poc/zcash-android-wallet-app/app/google-services.json`.
|
|
|
|
|
|
|
|
```
|
2019-04-23 11:12:03 -07:00
|
|
|
cd /mount/zcash-android-wallet-poc
|
|
|
|
cd zcash-android-wallet-app
|
|
|
|
./gradlew clean assembleZcashtestnetDebug
|
2019-04-23 11:18:13 -07:00
|
|
|
```
|
2019-04-23 11:12:03 -07:00
|
|
|
|
2019-04-16 21:44:17 -07:00
|
|
|
## Running the Stack
|
|
|
|
|
2019-04-23 15:17:32 -07:00
|
|
|
**This section assumes you've successfully run all of the builds in the Build
|
|
|
|
Cheat Sheet above.** We will set up:
|
2019-04-17 07:21:30 -07:00
|
|
|
|
|
|
|
1. A `zcashd` node connected to testnet.
|
2019-04-23 14:00:15 -07:00
|
|
|
2. A `lightwalletd` ingestor which receives blocks from the `zcashd` node.
|
|
|
|
3. A `lightwalletd` server which serves the blocks parsed by the ingestor to
|
2019-04-17 07:21:30 -07:00
|
|
|
light clients.
|
2019-04-23 15:17:32 -07:00
|
|
|
4. A patched build of `zcash-android-wallet-poc` (the demo Android app), running
|
|
|
|
in an emulator, connected to the `lightwalletd` server.
|
|
|
|
|
|
|
|
### Server-Side
|
2019-04-17 07:21:30 -07:00
|
|
|
|
2019-04-23 14:00:15 -07:00
|
|
|
First, start the `lightwalletd` ingestor:
|
2019-04-17 07:21:30 -07:00
|
|
|
|
|
|
|
```
|
|
|
|
cd /mount/lightwalletd
|
2019-04-23 14:00:15 -07:00
|
|
|
go run cmd/ingest/main.go -db-path database.db -log-file ingestor-log.txt
|
2019-04-17 07:21:30 -07:00
|
|
|
```
|
|
|
|
|
|
|
|
This will listen on port 28332 for a ZMQ connection from `zcashd`. Now put the
|
|
|
|
following contents in `/root/.zcash/zcash.conf`:
|
|
|
|
|
|
|
|
```
|
|
|
|
testnet=1
|
|
|
|
addnode=testnet.z.cash
|
|
|
|
zmqpubcheckedblock=tcp://127.0.0.1:28332
|
|
|
|
rpcuser=yourusername
|
|
|
|
rpcpassword=yourpassword
|
|
|
|
```
|
|
|
|
|
|
|
|
You're advised to change `yourusername` and `yourpassword` to something random.
|
|
|
|
This configures `zcashd` to sync with the testnet and send blocks to
|
|
|
|
`lightwalletd` on localhost port 28332. Now build and run `zcashd`:
|
|
|
|
|
|
|
|
```
|
|
|
|
cd /mount/zcash
|
|
|
|
./zcutil/build.sh -j$(nproc)
|
|
|
|
./zcutil/fetch-params.sh
|
|
|
|
./src/zcashd
|
|
|
|
```
|
|
|
|
|
2019-04-23 14:00:15 -07:00
|
|
|
If you check the contents of `/mount/lighwalletd/ingestor-log.txt`, you should
|
2019-04-17 07:21:30 -07:00
|
|
|
see that it is receiving blocks as the `zcashd` node syncs.
|
|
|
|
|
|
|
|
To serve these blocks to light clients, start the server:
|
|
|
|
|
|
|
|
```
|
|
|
|
cd /mount/lightwalletd
|
|
|
|
go run cmd/server/main.go -conf-file /root/.zcash/zcash.conf -db-path database.db -log-file server-log.txt
|
|
|
|
```
|
|
|
|
**Note:** If this command fails and there's an error message about database
|
2019-04-23 14:00:15 -07:00
|
|
|
locks in `server-log.txt` you need to stop the ingestor, start the server, then
|
|
|
|
re-start the ingestor.
|
2019-04-16 21:44:17 -07:00
|
|
|
|
2019-04-23 15:17:32 -07:00
|
|
|
After a while, `zcashd` will finish downloading all of the blocks, and as it
|
|
|
|
does so the ingestor will ingest them and the server will be able to serve them.
|
|
|
|
Once this is done, the mobile wallet will be able to connect and sync.
|
|
|
|
|
|
|
|
### Client-Side
|
|
|
|
|
|
|
|
First, we'll need to patch the demo app to be able to connect to our
|
|
|
|
`lightwalletd` server. Apply this patch:
|
|
|
|
|
|
|
|
```
|
|
|
|
diff --git a/zcash-android-wallet-app/app/src/main/java/cash/z/android/wallet/sample/SampleConfig.kt b/zcash-android-wallet-app/app/src/main/java/cash/z/android/wallet/sample/SampleConfig.kt
|
|
|
|
index 249da5c..d45c046 100644
|
|
|
|
--- a/zcash-android-wallet-app/app/src/main/java/cash/z/android/wallet/sample/SampleConfig.kt
|
|
|
|
+++ b/zcash-android-wallet-app/app/src/main/java/cash/z/android/wallet/sample/SampleConfig.kt
|
|
|
|
@@ -94,6 +94,7 @@ object MyWallet : WalletConfig {
|
|
|
|
|
|
|
|
enum class Servers(val host: String, val displayName: String) {
|
|
|
|
LOCALHOST("10.0.0.191", "Localhost"),
|
|
|
|
+ LOCALHOST2("10.0.2.2", "Localhost2"),
|
|
|
|
// WLAN("10.0.0.26"),
|
|
|
|
WLAN1("10.0.2.24", "WLAN Conference"),
|
|
|
|
WLAN2("192.168.1.235", "WLAN Office"),
|
|
|
|
diff --git a/zcash-android-wallet-app/app/src/main/res/values/strings.xml b/zcash-android-wallet-app/app/src/main/res/values/strings.xml
|
|
|
|
index a57ee92..560d204 100644
|
|
|
|
--- a/zcash-android-wallet-app/app/src/main/res/values/strings.xml
|
|
|
|
+++ b/zcash-android-wallet-app/app/src/main/res/values/strings.xml
|
|
|
|
@@ -108,6 +108,7 @@
|
|
|
|
<item>WLAN Office</item>
|
|
|
|
<item>WLAN Conference</item>
|
|
|
|
<item>Localhost</item>
|
|
|
|
+ <item>Localhost2</item>
|
|
|
|
<item>Custom...</item>
|
|
|
|
</string-array>
|
|
|
|
</resources>
|
|
|
|
```
|
|
|
|
|
|
|
|
Now rebuild the APK:
|
|
|
|
|
|
|
|
```
|
|
|
|
./gradlew clean assembleZcashtestnetRelease
|
|
|
|
```
|
|
|
|
|
|
|
|
To run the app in the Android emulator, first start a VNC server for the
|
|
|
|
emulator to use to serve its display:
|
|
|
|
|
|
|
|
```
|
|
|
|
vncserver :1 -geometry 1080x1920 -depth 24
|
|
|
|
```
|
|
|
|
|
|
|
|
This will output a message along the lines of:
|
|
|
|
|
|
|
|
```
|
|
|
|
...
|
|
|
|
New 'X' desktop is 3fe5a1e534df:1
|
|
|
|
...
|
|
|
|
```
|
|
|
|
|
|
|
|
Copy the `3fe...4df` part of your output and use it to replace the `fff...fff`
|
|
|
|
in the following command to start the emulator:
|
|
|
|
|
|
|
|
```
|
|
|
|
DISPLAY=ffffffffffff:1 $ANDROID_HOME/emulator/emulator -avd zemu -noaudio -no-boot-anim -gpu off -qemu
|
|
|
|
```
|
|
|
|
|
|
|
|
You can now install the APK in the emulator:
|
|
|
|
|
|
|
|
```
|
|
|
|
cd /mount/zcash-android-wallet-poc
|
|
|
|
$ANDROID_HOME/platform-tools/adb install ./zcash-android-wallet-app/app/build/outputs/apk/zcashtestnet/debug/app-zcashtestnet-debug.apk
|
|
|
|
```
|
|
|
|
|
|
|
|
From your *host* system, connect to the emulator with any VNC client, e.g...
|
|
|
|
|
|
|
|
```
|
|
|
|
vncviewer localhost:5901
|
|
|
|
```
|
|
|
|
|
|
|
|
You should now be able to control the emulated device and launch the app. To
|
2019-04-23 15:21:50 -07:00
|
|
|
connect to your `lightwalletd`, go in the app's settings and choose Localhost2,
|
2019-04-23 15:17:32 -07:00
|
|
|
apply, then restart the app.
|
|
|
|
|
2019-04-16 21:44:17 -07:00
|
|
|
## TODOs
|
|
|
|
|
2019-04-23 15:17:32 -07:00
|
|
|
- How to do a reindex to fix the database?
|
2019-04-16 21:44:17 -07:00
|
|
|
- Put `.zcash-mainnet` and `.zcash-testnet` fully loaded into the image.
|
2019-04-17 07:21:30 -07:00
|
|
|
- Make the builds use the output of dependencies' builds
|
2019-04-23 15:21:50 -07:00
|
|
|
- Verify the "running the stack" instructions are actually correct.
|
|
|
|
- Security review (are tools/code being downloaded safely? what are the
|
|
|
|
consequences of using a privileged docker? etc)
|