gaspersic/go-ethereum
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[DOCS] massive documentation update (#20229)

Browse Source 
This PR:

- reorganizes all documentation pages so they live in the right category
- removes lots of legacy docs
- contains many improvements to active documentation pages

Geth user documentation is now spread across five major categories:

- Install and Build: installation and compile instructions
- Using Geth: this is for pages about general geth usage.
- For dApp Developers: this is for programming guides and functionality specific
   to dapp development. All the dev guides for mobile framework and Go APIs live here.
- JSON-RPC APIs: this has its own section because there is now a sub-page for
   every name space. I have also added an overview text that explains how to set
   up the API servers.
- For Geth Developers: this is for geth contributors
This commit is contained in:
Felix Lange
2019-11-05 13:46:00 +01:00
committed by GitHub
parent 86b20d897e
commit 7416b05b81
76 changed files with 3537 additions and 4680 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/_getting-started/dev-mode.md
View File

@ -1,5 +1,6 @@
---
title: Dev mode
sort_key: B
---
Geth has a development mode which sets up a single node Ethereum test network with a number of options optimized for developing on local machines. You enable it with the `--dev` argument.

125
docs/_getting-started/index.md
View File

@ -1,104 +1,67 @@
---
title: Getting Started with Geth
permalink: getting-started
permalink: docs/getting-started
sort_key: A
---
## Installing
To use Geth, you need to install it first. You can install the geth software 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.
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.
For this tutorial, we'll assume you are comfortable with downloading a pre-built binary.
Head over to the [install and build](./install-and-build/installing-geth) section and
follow the instructions for your operating system if you wish to use a different
installation method.
### Install on macOS via Homebrew
### Downloading Geth
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/).
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.
Then run the following commands to add the tap and install geth:
To download Geth, go to the [Downloads page](https://geth.ethereum.org/downloads) and
select the latest stable release matching your platform.
```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:
We create the following archives:
- 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.
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.
### Creating an account
### 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:
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._
_[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.
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.
- **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:
@ -106,22 +69,24 @@ For example:
geth --syncmode "light"
```
### Connect to node
### Javascript Console
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:
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:
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
```js
> eth.accounts
```
You can also enter the console directly when you start the node with the `console` command:
```shell
geth --syncmode "light" console
geth console --syncmode "light"
```

125
docs/_getting-started/private-net.md Normal file
View File

@ -0,0 +1,125 @@
---
title: Private Network Tutorial
sort_key: B
---
This page describes how to set up a local cluster of nodes, advise how to make it private,
and how to hook up your nodes on the eth-netstat network monitoring app. A fully
controlled ethereum network is useful as a backend for network integration testing (core
developers working on issues related to networking/blockchain synching/message
propagation, etc or DAPP developers testing multi-block and multi-user scenarios).
We assume you are able to build `geth` following the [build instructions](../install-and-build/build-from-source)
## Setting up multiple nodes
In order to run multiple ethereum nodes locally, you have to make sure:
- each instance has a separate data directory (`--datadir`)
- each instance runs on a different port (both eth and rpc) (`--port and --rpcport`)
- in case of a cluster the instances must know about each other
- the ipc endpoint is unique or the ipc interface is disabled (`--ipcpath or --ipcdisable`)
You start the first node (let's make port explicit and disable ipc interface)
geth --datadir="/tmp/eth/60/01" -verbosity 6 --ipcdisable --port 30301 --rpcport 8101 console 2>> /tmp/eth/60/01.log
We started the node with the console, so that we can grab the enode url for instance:
> admin.nodeInfo.enode
enode://8c544b4a07da02a9ee024def6f3ba24b2747272b64e16ec5dd6b17b55992f8980b77938155169d9d33807e501729ecb42f5c0a61018898c32799ced152e9f0d7@9[::]:30301
`[::]` will be parsed as localhost (`127.0.0.1`). If your nodes are on a local network
check each individual host machine and find your ip with `ifconfig` (on Linux and MacOS):
$ ifconfig|grep netmask|awk '{print $2}'
127.0.0.1
192.168.1.97
If your peers are not on the local network, you need to know your external IP address (use
a service) to construct the enode url.
Now you can launch a second node with:
geth --datadir="/tmp/eth/60/02" --verbosity 6 --ipcdisable --port 30302 --rpcport 8102 console 2>> /tmp/eth/60/02.log
If you want to connect this instance to the previously started node you can add it as a
peer from the console with `admin.addPeer(enodeUrlOfFirstInstance)`.
You can test the connection by typing in geth console:
> net.listening
true
> net.peerCount
1
> admin.peers
...
## Local cluster
As an extention of the above, you can spawn a local cluster of nodes easily. It can also
be scripted including account creation which is needed for mining. See
[`gethcluster.sh`](https://github.com/ethersphere/eth-utils) script, and the README there
for usage and examples.
## Private network
See [[the Private Network Page|Private network]] for more information.
### Setup bootnode
The first time a node connects to the network it uses one of the predefined
[bootnodes](https://github.com/ethereum/go-ethereum/blob/master/params/bootnodes.go).
Through these bootnodes a node can join the network and find other nodes. In the case of a
private cluster these predefined bootnodes are not of much use. Therefore go-ethereum
offers a bootnode implementation that can be configured and run in your private network.
It can be run through the command.
> bootnode
Fatal: Use -nodekey or -nodekeyhex to specify a private key
As can be seen the bootnode asks for a key. Each ethereum node, including a bootnode is
identified by an enode identifier. These identifiers are derived from a key. Therefore you
will need to give the bootnode such key. Since we currently don't have one we can instruct
the bootnode to generate a key (and store it in a file) before it starts.
> bootnode -genkey bootnode.key
I0216 09:53:08.076155 p2p/discover/udp.go:227] Listening, enode://890b6b5367ef6072455fedbd7a24ebac239d442b18c5ab9d26f58a349dad35ee5783a0dd543e4f454fed22db9772efe28a3ed6f21e75674ef6203e47803da682@
(exit with CTRL-C)
The stored key can be seen with:
> cat bootnode.key
dc90f8f7324f1cc7ba52c4077721c939f98a628ed17e51266d01c9cd0294033a
To instruct geth nodes to use our own bootnode(s) use the `--bootnodes` flag. This is a
comma separated list of bootnode enode identifiers.
geth --bootnodes "enode://890b6b5367ef6072455fedbd7a24ebac239d442b18c5ab9d26f58a349dad35ee5783a0dd543e4f454fed22db9772efe28a3ed6f21e75674ef6203e47803da682@[::]:30301"
(what `[::]` means is explained previously)
Since it is convenient to start the bootnode each time with the same enode we can give the
bootnode program the just generated key on the next time it is started.
bootnode -nodekey bootnode.key
I0216 10:01:19.125600 p2p/discover/udp.go:227] Listening, enode://890b6b5367ef6072455fedbd7a24ebac239d442b18c5ab9d26f58a349dad35ee5783a0dd543e4f454fed22db9772efe28a3ed6f21e75674ef6203e47803da682@[::]:30301
or
bootnode -nodekeyhex dc90f8f7324f1cc7ba52c4077721c939f98a628ed17e51266d01c9cd0294033a
I0216 10:01:40.094089 p2p/discover/udp.go:227] Listening, enode://890b6b5367ef6072455fedbd7a24ebac239d442b18c5ab9d26f58a349dad35ee5783a0dd543e4f454fed22db9772efe28a3ed6f21e75674ef6203e47803da682@[::]:30301
## Monitoring your nodes
[This page](https://github.com/ethereum/wiki/wiki/Network-Status) describes how to use the
[The Ethereum (centralised) network status monitor](eth-stats). to monitor your nodes.
[This page](monitoring) or [this README](https://github.com/ethersphere/eth-utils)
describes how you set up your own monitoring service for a (private or public) local
cluster.
[eth-stats]: https://ethstats.org
[monitoring]: ../doc/setting-up-monitoring-on-local-cluster