docs: add user documentation on how to use Zebra with docker (#5504)

* docs: add user documentation on how to use Zebra with docker Motivation: We don't have a user documentation on how to use/deploy Zebra using our the Dockerfile available in our repository or were the images are being hosted Solution: Add user documentation explaining how to pull the image from the Docker Hub or how to build it locally. With extra information on which images we're hosting and where we're hosting it * docs(docker): use existing getting started header * Update book/src/user/docker.md Co-authored-by: Arya <[email protected]> * docs(docker): add build alternative instructions from Docker * docs: add docker documentation to Rust doc sidebar * docs: update checklist with docker user documentation * Update README.md Co-authored-by: teor <[email protected]> * Update new refs to rc.1 Co-authored-by: Arya <[email protected]> Co-authored-by: teor <[email protected]> Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
ZcashFoundation · Nov 1, 2022 · 4835970 · 4835970
1 parent bbbd56d
commit 4835970
Show file tree

Hide file tree

Showing 4 changed files with 52 additions and 7 deletions.
diff --git a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md
@@ -42,6 +42,7 @@ zebrad (rc):
 - [ ] zebrad `Cargo.toml`
 - [ ] `zebra-network` protocol user agent: https://github.com/ZcashFoundation/zebra/blob/main/zebra-network/src/constants.rs
 - [ ] `README.md`
+- [ ] `book/src/user/docker.md`
 
 crates (pre-release):
 - [ ] zebra-* `Cargo.toml`s

diff --git a/README.md b/README.md
@@ -52,8 +52,7 @@ You would want to run Zebra if you want to contribute to the
 Zcash network: the more nodes are run, the more reliable the network will be
 in terms of speed and resistance to denial of service attacks, for example.
 
-Zebra aims to be
-[faster, more secure, and more easily extensible](https://doc.zebra.zfnd.org/zebrad/index.html#zebra-advantages)
+Zebra aims to be [faster, more secure, and more easily extensible](https://doc.zebra.zfnd.org/zebrad/index.html#zebra-advantages)
 than other Zcash implementations.
 
 ## Release Candidates
@@ -72,13 +71,13 @@ Currently, Zebra validates all of the Zcash consensus rules for the NU5 network
 You can run Zebra using our Docker image.
 This command will run our latest release, and sync it to the tip:
 
-<!-- TODO: replace with `docker run zfnd/zebra` when we release 1.0.0 -->
-
-```sh
-docker run zfnd/zebra:1.0.0-rc.0
+```shell
+docker run --detach zfnd/zebra:1.0.0-rc.0
 ```
 
-You can also [enable Zebra's RPC port](https://github.com/ZcashFoundation/zebra#configuring-json-rpc-for-lightwalletd) and [configure other features](https://zebra.zfnd.org/user/run.html).
+For more information, read our [Docker documentation](book/src/user/docker.md).
+
+> You can also [enable Zebra's RPC port](https://github.com/ZcashFoundation/zebra#configuring-json-rpc-for-lightwalletd) and [configure other features](https://zebra.zfnd.org/user/run.html).
 
 ### Build Instructions
 

diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -5,6 +5,7 @@
   - [Zebra System Requirements](user/requirements.md)
   - [Installing Zebra](user/install.md)
   - [Running Zebra](user/run.md)
+  - [Zebra with Docker](user/docker.md)
   - [Tracing Zebra](user/tracing.md)
   - [Zebra Metrics](user/metrics.md)
   - [Lightwalletd](user/lightwalletd.md)

diff --git a/book/src/user/docker.md b/book/src/user/docker.md
@@ -0,0 +1,44 @@
+# Zebra with Docker
+
+The easiest way to run Zebra is using [Docker](https://docs.docker.com/get-docker/). 
+
+We've embraced Docker in Zebra for most of the solution lifecycle, from development environments to CI (in our pipelines), and deployment to end users. 
+
+## Quick usage
+
+You can deploy Zebra for a daily use with the images available in [Docker Hub](https://hub.docker.com/repository/docker/zfnd/zebra) or build it locally for testing
+
+### Ready to use image
+
+```shell
+docker run --detach zfnd/zebra:1.0.0-rc.1
+```
+
+### Build it locally
+
+```shell
+git clone --depth 1 --branch v1.0.0-rc.1 [email protected]:ZcashFoundation/zebra.git
+docker build --file docker/Dockerfile --target runtime --tag zebra:local
+docker run --detach zebra:local
+```
+
+### Alternatives
+
+See the Zebra [build instructions](https://github.com/ZcashFoundation/zebra#build-instructions).
+
+## Images
+
+The Zebra team builds multiple images with a single [Dockerfile](https://github.com/ZcashFoundation/zebra/blob/main/docker/Dockerfile) using [multistage builds](https://docs.docker.com/build/building/multi-stage/). The `test` stage adds needed features and tools (like [lightwalletd](https://github.com/adityapk00/lightwalletd)) and the `runtime` stage just adds the *zebrad* binary and required *zcash-params* for Zebra to run correctly.
+
+As a result the Zebra team builds four images:
+
+- [zcash-params](us-docker.pkg.dev/zealous-zebra/zebra/zcash-params): built Zcash network parameters
+- [lightwalletd](us-docker.pkg.dev/zealous-zebra/zebra/lightwalletd): a backend service that provides an interface to the Zcash blockchain
+- [zebrad-test](us-docker.pkg.dev/zealous-zebra/zebra/zebrad-test): a zebrad binary with lightwalletd included, and test suites enabled
+- [zebra](https://hub.docker.com/repository/docker/zfnd/zebra): a streamlined version with the zebrad binary and just the needed features needed to run *as-is*
+
+## Registries
+
+The images built by the Zebra team are all publicly hosted. Old image versions meant to be used by our [CI pipeline](https://github.com/ZcashFoundation/zebra/blob/main/.github/workflows/continous-integration-docker.yml) (`zebrad-test`, `lighwalletd`) might be deleted on a scheduled basis.
+
+We use [Docker Hub](https://hub.docker.com/repository/docker/zfnd/zebra) for end-user images and [Google Artifact Registry](https://console.cloud.google.com/artifacts/docker/zealous-zebra/us/zebra) to build external tools and test images