From 06c70fff5eea285e983725465c72b6a28e2e577a Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Wed, 30 Oct 2019 12:34:07 +0100 Subject: [PATCH] [DOCS] Add Getting started guide (#20088) --- _config.yml | 23 +++--- _data/sidebar.yml | 3 +- docs/_getting-started/index.md | 127 +++++++++++++++++++++++++++++++++ 3 files changed, 143 insertions(+), 10 deletions(-) create mode 100644 docs/_getting-started/index.md diff --git a/_config.yml b/_config.yml index a90ab5b6d..8b0da6993 100644 --- a/_config.yml +++ b/_config.yml @@ -25,51 +25,56 @@ default_root: "../.." collections_dir: docs collections: + getting-started: + output: true + caption: Getting started + sidebar_index: 1 + frontpage: _getting-started/index.md install-and-build: output: true permalink: docs/:collection/:slug caption: Install and build - sidebar_index: 1 + sidebar_index: 2 frontpage: _install-and-build/Installing-Geth.md interface: output: true permalink: docs/:collection/:slug caption: Interacting with Geth - sidebar_index: 2 + sidebar_index: 3 support: output: true permalink: docs/:collection/:slug caption: Issues and support - sidebar_index: 3 + sidebar_index: 4 developers: output: true permalink: docs/:collection/:slug caption: Developer docs - sidebar_index: 4 + sidebar_index: 5 clef: output: true permalink: docs/:collection/:slug caption: Clef - sidebar_index: 5 + sidebar_index: 6 frontpage: _clef/Overview.md whisper: output: true permalink: docs/:collection/:slug caption: Whisper - sidebar_index: 6 + sidebar_index: 7 frontpage: _whisper/Whisper-Overview.md rpc: output: true permalink: docs/:collection/:slug caption: JSON RPC APIs - sidebar_index: 7 + sidebar_index: 8 doc: output: true permalink: docs/:collection/:slug caption: Other - sidebar_index: 8 + sidebar_index: 9 legacy: output: true permalink: docs/:collection/:slug caption: Legacy content - sidebar_index: 9 + sidebar_index: 10 diff --git a/_data/sidebar.yml b/_data/sidebar.yml index ba1bcbe00..890c9e1ee 100644 --- a/_data/sidebar.yml +++ b/_data/sidebar.yml @@ -1,3 +1,4 @@ +Getting started: Install and build: - Downloads: /downloads - Installing Ethereum: /docs/Building-Ethereum @@ -20,4 +21,4 @@ Developers: - Mobile Clients: /docs/Mobile-Clients/Libraries-and-Inproc-Ethereum-Nodes - Native DApps: /docs/Native-DApps/Go-bindings-to-Ethereum-contracts - Active go-ethereum projects: /docs/Active-go-ethereum-projects - - Other documents: /docs/other-documents \ No newline at end of file + - Other documents: /docs/other-documents diff --git a/docs/_getting-started/index.md b/docs/_getting-started/index.md new file mode 100644 index 000000000..eec668f94 --- /dev/null +++ b/docs/_getting-started/index.md @@ -0,0 +1,127 @@ +--- +title: Getting Started with Geth +permalink: getting-started +--- + +## Installing + +You can install the Go implementation of Ethereum in a variety of ways. These include installing it via your favorite package manager; downloading a standalone pre-built binary; running as a docker container; or building it yourself. This section highlights the common options, but you can find others in the left hand menu, or in the [install and build](/install-and-build/Installing-Geth) section. + +### Install on macOS via Homebrew + +You can install go-ethereum on macOS using [our Homebrew tap](https://github.com/ethereum/homebrew-ethereum). If you don't have Homebrew, [install it first](http://brew.sh/). + +Then run the following commands to add the tap and install geth: + +```shell +brew tap ethereum/ethereum +brew install ethereum +``` + +_[Read this guide](/install-and-build/Installing-Geth#install-on-macos-via-homebrew) further Homebrew options._ + +### Install on Ubuntu via PPAs + +You can install go-ethereum on Ubuntu-based distributions using the built-in launchpad PPAs (Personal Package Archives). We provide a single PPA repository with both our stable and our development releases for Ubuntu versions `trusty`, `xenial`, `zesty` and `artful`. + +Install dependencies first: + +```shell +sudo apt-get install software-properties-common +``` + +To enable our launchpad repository run: + +```shell +sudo add-apt-repository -y ppa:ethereum/ethereum +``` + +After that you can install the stable version of go-ethereum: + +```shell +sudo apt-get update +sudo apt-get install ethereum +``` + +_[Read this guide](/install-and-build/Installing-Geth#install-on-ubuntu-via-ppas) for further Ubuntu options._ + +### Install on Windows + +_Although we were shipping Chocolatey packages for a time after the Frontier release, the constant manual approval process led to us stopping distribution. We will try to negotiate trusted package status for go-ethereum so the Chocolatey option is available again._ + +Until then grab a Windows installer from our [downloads](https://geth.ethereum.org/downloads) page. + +### Download standalone binary + +We distribute all our stable releases and development builds as standalone binaries. These are useful for scenarios where you'd like to: a) install a specific version of our code (e.g., for reproducible environments); b) install on machines without internet access (e.g., air gapped computers); or c) do not like automatic updates and would rather manually install software. + +We create the following standalone binaries: + +- 32bit, 64bit, ARMv5, ARMv6, ARMv7 and ARM64 archives (`.tar.gz`) on Linux +- 64bit archives (`.tar.gz`) on macOS +- 32bit and 64bit archives (`.zip`) and installers (`.exe`) on Windows + +For all binaries we provide two options, one containing only Geth, and another containing Geth along with all the developer tools from our repository (`abigen`, `bootnode`, `disasm`, `evm`, `rlpdump`). Read our [`README`](https://github.com/ethereum/go-ethereum#executables) for more information about these executables. + +To download these binaries, head to the [Go Ethereum Downloads](https://geth.ethereum.org/downloads) page. + +### Run inside docker container + +We maintain a Docker image with recent snapshot builds from our `develop` branch on DockerHub. In addition to the container based on Ubuntu (158 MB), there is a smaller image using Alpine Linux (35 MB). To use the alpine [tag](https://hub.docker.com/r/ethereum/client-go/tags), replace `ethereum/client-go` with `ethereum/client-go:alpine` in the examples below. + +To pull the image and start a node, run these commands: + +```shell +docker pull ethereum/client-go +docker run -it -p 30303:30303 ethereum/client-go +``` + +_[Read this guide](/install-and-build/Installing-Geth#run-inside-docker-container) for further Docker options._ + +## Starting a node + +### Create an account + +Before starting Geth you first need to create an account that represents a key pair. Use the following command to create a new account and set a password for that account: + +```shell +geth account new +``` + +_[Read this guide](/interface/Managing-your-accounts) for more details on importing existing Ethereum accounts and other uses of the `account` command._ + +### Sync modes + +Running Geth starts an Ethereum node that can join any existing network, or create a new one. You can start Geth in one of three different sync modes using the `--syncmode "{mode}"` argument that determines what sort of node it is in the network. + +These are: + +- **Full**: Downloads all blocks (including headers, transactions and receipts) and generates the state of the blockchain incrementally by executing every block. +- **Fast** (Default): Downloads all blocks (including headers, transactions and receipts), verifies all headers, and downloads the state and verifies it against the headers. +- **Light**: Downloads all block headers, block data, and verifies some randomly. + +For example: + +```shell +geth --syncmode "light" +``` + +### Connect to node + +Once you have an account and Geth is running, you can interact with it by opening another terminal and using the following command to open a JavaScript console: + +```shell +geth attach +``` + +In the console you can issue any of the Geth commands, for example, to list all the accounts on the node, use: + +```shell +eth.accounts +``` + +You can also enter the console directly when you start the node with the `console` command: + +```shell +geth --syncmode "light" console +```