Add `doc/book/src/user/installation.md` and remove `readthedocs.io` references. #6779

nathan-at-least · 2023-10-26T15:19:55Z

Context: we used to host some docs on https://zcash.readthedocs.io/en/latest/rtd_pages/zcashd.html ~~and that's gone~~ so we're striving to consolidate docs into the zcashd book in this repo.

Edit 2024-04-25: that page on readthedocs was restored.

This adds an installation page to the book, which (currently) only contains Debian instructions.

Important details:

I got the instructions from zcash.readthedocs.io in the wayback machine, then dusted them off a bit, including updating the apt signing key fingerprint and removing zcash-fetch-params step. I also followed those instructions on a Debian Bullseye vm.
I updated doc/release-process.md to check that apt fingerprint in the pre-release process.
I tweaked the top-level README.md to replace readthedocs links with internal mdbook links. The issue here is that this works/makes sense in an mdbook rendering, but may be confusing in the top-level README.md context (such as github repo homepage). I added an html comment in order to help local file readers make the connection.

…/installation.md` with debian instructions.

…ase checklist for apt fingerprint.

nathan-at-least · 2023-10-26T15:25:19Z

This should resolve #6778 .

str4d · 2023-11-02T01:27:49Z

CONTRIBUTING.md

@@ -1 +1 @@
-Please read [our Development Guidelines](https://zcash.readthedocs.io/en/latest/rtd_pages/development_guidelines.html).
+Please read [our Development Guidelines](doc/book/src/dev.md).


This link is to the top-level page for the developer documentation, which doesn't have any of the necessary information and isn't rendered with links. We should either change this to point to the rendered version:

Suggested change

Please read [our Development Guidelines](doc/book/src/dev.md).

Please read [our Development Documentation](https://zcash.github.io/zcash/dev.html).

or recreate the developer documentation page. For now I suggest changing the link.

str4d · 2023-11-02T01:29:16Z

doc/book/src/user/installation.md

+
+```
+wget -qO - https://apt.z.cash/zcash.asc | gpg --import
+gpg --export B1C9095EAA1848DBB54D9DDA1D05FDC66B372CFE | sudo apt-key add -


I have not verified this key handle.

I calculated this with these commands:

$ wget -qO - https://apt.z.cash/zcash.asc | gpg --import gpg: key 1D05FDC66B372CFE: "Zcash Master Signing Key (Electric Coin Company) <sysadmin@z.cash>" not changed gpg: Total number processed: 1 gpg: unchanged: 1 $ gpg --fingerprint 1D05FDC66B372CFE pub rsa3072 2023-06-19 [SC] B1C9 095E AA18 48DB B54D 9DDA 1D05 FDC6 6B37 2CFE uid [ unknown] Zcash Master Signing Key (Electric Coin Company) <sysadmin@z.cash> sub rsa3072 2023-06-19 [E] $ gpg --fingerprint 1D05FDC66B372CFE | grep 2CFE | sed 's/ *//g' B1C9095EAA1848DBB54D9DDA1D05FDC66B372CFE

So this is relying on apt.z.cash (and the wget/tls/gpg toolchain). We should verify this matches the debian signing keypair we use for deploying those packages.

The key used is the correct one, it is the one used for debian package releases.

str4d · 2023-11-02T01:32:37Z

INSTALL

-See the Zcash documentation wiki (https://zcash.readthedocs.io/en/latest/rtd_pages/zcashd.html) for instructions on building zcashd,
-the intended-for-services, no-graphical-interface, reference
-implementation of Zcash.
+See [the Zcashd book](doc/book/src/) for installation, build, and operation instructions.


We should link to the rendered version in this case (as this file is aimed at users, not contributors):

Suggested change

See [the Zcashd book](doc/book/src/) for installation, build, and operation instructions.

See [the `zcashd` book](https://zcash.github.io/zcash/) for installation, build, and operation instructions.

str4d · 2023-11-02T01:35:07Z

README.md

-* :blue_book: See the documentation at the [ReadTheDocs](https://zcash.readthedocs.io)
-  for help and more information.


Revert this removal and change it to See [the `zcashd` book](https://zcash.github.io/zcash/)

nathan-at-least · 2023-11-02T19:32:40Z

TODO:

consider rebase atop Migrate Zcashd build instructions from readthedocs #6633, then integrating these two.

daira · 2023-11-18T23:40:43Z

README.md

-for instructions on joining the main Zcash network.
+Please see our [user documentation](user.md) for instructions on joining the main Zcash network.
+
+<!-- Relative link destinations like `user.md` live under `./doc/book/src`. -->


It would be possible to make this link Just Work, at least on a Unix checkout:

Move all book content into a subdirectory, say guide.

Symlink guide to doc/book/src/guide.

daira · 2023-11-18T23:45:05Z

doc/book/src/user/installation.md

+
+## Different Instruction Sets
+
+Only x86-64 processors are supported.


Is this true? We have Tier 3 support for aarch64-linux-gnu.

daira · 2023-11-18T23:47:44Z

doc/book/src/user/installation.md

+
+If you’re starting from a new virtual machine, sudo may not come installed. See this issue for instructions to get up and running: https://github.com/zcash/zcash/issues/1844
+
+## libgomp1 or libstdc++6 version problems


libgomp1 was related to OpenMP which we no longer use. Also we don't dynamically link to libstdc++6 any more, we statically link libc++. This whole section should be removed. (Definitely trying to "upgrade" to gcc/g++ 4.9 will not help; that is very out-of-date advice.)

daira · 2023-11-18T23:51:16Z

doc/book/src/user/installation.md

+
+## Tor
+
+The repository is also accessible via Tor, after installing the apt-transport-tor package, at the address zcaptnv5ljsxpnjt.onion. Use the following pattern in your sources.list file:


Please check that this still works, and delete the section if not.

daira · 2023-11-18T23:52:41Z

doc/book/src/user/installation.md

+sudo apt-key del AEFD26F966E279CD
+```
+
+Then [retrieve the latest key](#fetching-a-new-signing-key), then rerun `sudo apt update`.


Suggested change

Then [retrieve the latest key](#fetching-a-new-signing-key), then rerun `sudo apt update`.

[Retrieve the latest key](#fetching-a-new-signing-key), then rerun `sudo apt update`.

daira

The request to remove the section on libgomp1 and libstdc++6 is blocking.

nate added 3 commits October 26, 2023 07:51

Do a README.md pass to remove read-the-docs; add `doc/book/src/user…

e11fcbb

…/installation.md` with debian instructions.

Update doc/release-process.md to replace readthedocs.io w/ pre-rele…

5ae0b2e

…ase checklist for apt fingerprint.

Remove all readthedocs.io references.

bcb62ee

nathan-at-least requested review from nuttycom and str4d October 26, 2023 15:19

nathan-at-least added A-documentation Area: Documentation C-tech-debt Category: Technical debt that needs to be paid off Death By A Thousand Cuts labels Oct 26, 2023

str4d added this to the Release 5.8.0 milestone Nov 2, 2023

str4d requested changes Nov 2, 2023

View reviewed changes

daira reviewed Nov 18, 2023

View reviewed changes

daira requested changes Nov 18, 2023

View reviewed changes

str4d modified the milestones: Release 5.8.0, Post 5.8.0 Dec 21, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add `doc/book/src/user/installation.md` and remove `readthedocs.io` references. #6779

Add `doc/book/src/user/installation.md` and remove `readthedocs.io` references. #6779

nathan-at-least commented Oct 26, 2023 •

edited by daira

nathan-at-least commented Oct 26, 2023

str4d Nov 2, 2023

str4d Nov 2, 2023

nathan-at-least Nov 2, 2023

y4ssi Nov 2, 2023

str4d Nov 2, 2023

str4d Nov 2, 2023

nathan-at-least commented Nov 2, 2023 •

edited

daira Nov 18, 2023

daira Nov 18, 2023

daira Nov 18, 2023 •

edited

daira Nov 18, 2023

daira Nov 18, 2023

daira left a comment

		@@ -1 +1 @@
		Please read [our Development Guidelines](https://zcash.readthedocs.io/en/latest/rtd_pages/development_guidelines.html).
		Please read [our Development Guidelines](doc/book/src/dev.md).

	Please read [our Development Guidelines](doc/book/src/dev.md).
	Please read [our Development Documentation](https://zcash.github.io/zcash/dev.html).

	See [the Zcashd book](doc/book/src/) for installation, build, and operation instructions.
	See [the `zcashd` book](https://zcash.github.io/zcash/) for installation, build, and operation instructions.

		* :blue_book: See the documentation at the [ReadTheDocs](https://zcash.readthedocs.io)
		for help and more information.


		## Different Instruction Sets

		Only x86-64 processors are supported.


		If you’re starting from a new virtual machine, sudo may not come installed. See this issue for instructions to get up and running: https://github.com/zcash/zcash/issues/1844

		## libgomp1 or libstdc++6 version problems


		## Tor

		The repository is also accessible via Tor, after installing the apt-transport-tor package, at the address zcaptnv5ljsxpnjt.onion. Use the following pattern in your sources.list file:

	Then [retrieve the latest key](#fetching-a-new-signing-key), then rerun `sudo apt update`.
	[Retrieve the latest key](#fetching-a-new-signing-key), then rerun `sudo apt update`.

Add doc/book/src/user/installation.md and remove readthedocs.io references. #6779

Are you sure you want to change the base?

Add doc/book/src/user/installation.md and remove readthedocs.io references. #6779

Conversation

nathan-at-least commented Oct 26, 2023 • edited by daira

nathan-at-least commented Oct 26, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nathan-at-least commented Nov 2, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

daira Nov 18, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

daira left a comment

Choose a reason for hiding this comment

Add `doc/book/src/user/installation.md` and remove `readthedocs.io` references. #6779

Add `doc/book/src/user/installation.md` and remove `readthedocs.io` references. #6779

nathan-at-least commented Oct 26, 2023 •

edited by daira

nathan-at-least commented Nov 2, 2023 •

edited

daira Nov 18, 2023 •

edited