From 4835970bb700844e9930ea9d14910255f73913ee Mon Sep 17 00:00:00 2001 From: Gustavo Valverde Date: Tue, 1 Nov 2022 01:47:37 -0400 Subject: [PATCH] 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 * 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 * Update new refs to rc.1 Co-authored-by: Arya Co-authored-by: teor Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> --- .../release-checklist.md | 1 + README.md | 13 +++--- book/src/SUMMARY.md | 1 + book/src/user/docker.md | 44 +++++++++++++++++++ 4 files changed, 52 insertions(+), 7 deletions(-) create mode 100644 book/src/user/docker.md diff --git a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md index 7b86a4440..ebbea0ca6 100644 --- 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 index 80457fc66..2c3bcac2c 100644 --- 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: - - -```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 index 9b0023865..01581badf 100644 --- 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 new file mode 100644 index 000000000..7953be3bb --- /dev/null +++ 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 git@github.com: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