From 855c3e849dcef9eb8f8ae62d8cdd10f470ea8400 Mon Sep 17 00:00:00 2001 From: Sacha Saint-Leger Date: Wed, 10 Feb 2021 17:29:48 +0100 Subject: [PATCH] update intro and binary distribution edits (#2306) * update intro and binary distribution edits * stefan's suggestions --- .../src/distribution_internals.md | 51 +++++++++---------- docs/the_nimbus_book/src/intro.md | 16 ++---- 2 files changed, 27 insertions(+), 40 deletions(-) diff --git a/docs/the_nimbus_book/src/distribution_internals.md b/docs/the_nimbus_book/src/distribution_internals.md index a6fed6ab1..443dff334 100644 --- a/docs/the_nimbus_book/src/distribution_internals.md +++ b/docs/the_nimbus_book/src/distribution_internals.md @@ -2,56 +2,53 @@ ## Reproducibility -The binaries we build in GitHub Actions and distribute in GitHub releases come -from a convoluted process meant to ensure [reproducibility](https://reproducible-builds.org/). +The binaries we build in GitHub Actions and distribute in [our releases](https://github.com/status-im/nimbus-eth2/releases) come +from an intricate process meant to ensure [reproducibility](https://reproducible-builds.org/). -While being able to produce the same exact binaries from the corresponding Git -commits is a good idea for any open source project, it becomes a requirement -for software that deals with digital tokens. +While the ability to produce the same exact binaries from the corresponding Git +commits is a good idea for any open source project, it is a requirement +for software that deals with digital tokens of significant value. ## Docker containers for internal use -The easiest way to guarantee that users will be able to replicate those -binaries is to give them the same software environment we used in CI. Docker +The easiest way to guarantee that users are able to replicate +our binaries for themselves is to give them the same software environment we used in CI. Docker containers fit the bill, so everything starts with the architecture- and -OS-specific containers in "docker/dist/base\_image/". +OS-specific containers in `docker/dist/base\_image/`. -These images have all the packages we need, are built and published once (to -Docker Hub), then reused for a long time as the basis for temporary Docker -images where the nimbus-eth2 build is done. +These images contain all the packages we need, are built and published once (to +Docker Hub), and are then reused as the basis for temporary Docker +images where the `nimbus-eth2` build is carried out. -These temporary images are controlled by Dockerfiles in "docker/dist/" and, -since we're not publishing them anywhere, we can customize them to the system -they run on, by making them use the host's UID/GID, the host's QEMU static -binaries, etc. They get access to the source code through the use of external volumes. +These temporary images are controlled by Dockerfiles in `docker/dist/`. Since we're not publishing them anywhere, we can customize them to the system +they run on (we ensure they use the host's UID/GID, the host's QEMU static +binaries, etc); they get access to the source code through the use of external volumes. ## Build process -It all starts from the GitHub actions in ".github/workflows/release.yml". There +It all starts from the GitHub actions in `.github/workflows/release.yml`. There is a different job for each supported OS-architecture combination and they all run in parallel (ideally). -The "build-amd64" CI job is special, because it's the one that creates a new +The `build-amd64` CI job is special, because it creates a new GitHub release draft, as soon as possible. All the other jobs will upload their -binary distribution tarballs to this draft release but, since it's not feasible -to communicate between CI jobs, they'll just use GitHub APIs to find out what -the latest release is, check that it has the right Git tag, and use it as their +binary distribution tarballs to this draft release, but, since it's not feasible +to communicate between CI jobs, they simply use GitHub APIs to find out what +the latest release is, check that it has the right Git tag, and use that as their last step. The build itself is triggered by a Make target: `make dist-amd64`. This invokes -"scripts/make\_dist.sh" which builds the corresponding Docker container from -"docker/dist/" and runs it with the Git repository's top dir as an external +`scripts/make\_dist.sh` which builds the corresponding Docker container from +`docker/dist/` and runs it with the Git repository's top directory as an external volume. -The entry point for that container is "docker/dist/entry\_point.sh" and that's +The entry point for that container is `docker/dist/entry\_point.sh` and that's where you'll find the Make invocations needed to finally build the software and create distributable tarballs. ## Docker images for end users -Also in ".github/workflows/release.yml", but only for the "build-amd64" job, we -unpack the distribution tarball and copy its content into a third type of Docker -image - this one meant for end users and defined by "docker/dist/binaries/Dockerfile.amd64". +Configured in `.github/workflows/release.yml` (exclusively for the `build-amd64` job): we unpack the distribution tarball and copy its content into a third type of Docker image - this one meant for end users and defined by `docker/dist/binaries/Dockerfile.amd64`. -We publish that to [Docker Hub](https://hub.docker.com/r/statusim/nimbus-eth2). +We then publish that to [Docker Hub](https://hub.docker.com/r/statusim/nimbus-eth2). diff --git a/docs/the_nimbus_book/src/intro.md b/docs/the_nimbus_book/src/intro.md index 4f7780338..2fe377b50 100644 --- a/docs/the_nimbus_book/src/intro.md +++ b/docs/the_nimbus_book/src/intro.md @@ -4,11 +4,11 @@ Nimbus is a client implementation for both Ethereum 2.0 and Ethereum 1.0 that st > If you're eager to get started, check out our [quickstart guide](./quick-start.md). -However, resource-restricted hardware is not the only thing Nimbus is good for. Its low resource consumption makes it easy to run Nimbus together with other workloads on your server (this is especially valuable for eth2 stakers looking to lower the cost of their server instances). +However, resource-restricted hardware is not the only thing Nimbus is good for. Its low resource consumption makes it easy to run Nimbus together with other workloads on your server (this is especially valuable for stakers looking to lower the cost of their server instances). This book explains the ways in which you can use Nimbus to either monitor the eth2 chain or become a fully-fledged validator. -> The reality is that we are very early in the eth2 validating life cycle. Validating is not for everyone yet, and it comes with both risks and responsibilities. It isn't a particularly easy way to make money. You'll need to put effort into updating your software, researching hard-forks, having a robust setup... . As such, you should only stake if you are genuinely interested in securing the protocol. +> **N.B.** The reality is that we are very early in the eth2 validating life cycle. Validating is not for everyone yet, and it comes with both risks and responsibilities. It isn't a particularly easy way to make money. You'll need to put effort into updating your software, researching hard-forks, having a robust setup... . As such, you should only stake if you are genuinely interested in securing the protocol. @@ -29,17 +29,7 @@ Eth2 is a multi-year plan to improve the scalability, security, and programmabil In contrast to the Ethereum chain, as it currently stands, eth2 uses proof-of-stake (PoS) to secure its network. And while Ethereum as you know and love it will continue to exist as its own independent proof-of-work chain for a little while to come, the transition towards PoS starts now. -In traditional PoW, block proposers are called **_miners_**, whereas in PoS, they are called **_validators_**. In essence, _miners_ rely on actual hardware (such as some specifically manufactured mining machines), while _validators_ rely on software (such as Nimbus) and a good network connection. - -### Why Nimbus? - -In a sentence, Nimbus aims to be an ethereum client for resource-restricted devices. - -Because we believe that the largest deployment of Ethereum will be on embedded systems, Nimbus is being designed to perform well on IoT and personal mobile devices, including older smartphones with resource-restriced hardware. - -Although Nimbus will support full and archival nodes, its main implementation will be as a light client, with a focus on Proof of Stake and sharding. - -All our code is open source; we encourage you to keep track of our activity on [GitHub](https://github.com/status-im/nimbus). You can also keep up to date with our progress through the [Nimbus blog](https://our.status.im/tag/nimbus/). +> In traditional PoW, block proposers are called **_miners_**, whereas in PoS, they are called **_validators_**. In essence, _miners_ rely on actual hardware (such as some specifically manufactured mining machines), while _validators_ rely on software (such as Nimbus) and a good network connection. ### Get in touch