cerc-io/ipld-eth-server
18
0
Fork 1
Code Issues 10 Pull Requests 1 Actions Packages Projects Releases 37 Wiki Activity

Add several improvements to README.md (#28)

Browse Source 
- Expand instructions around technical specifics of project
  setup, including special gotchas in Ubuntu-based
  environments
- Add statement of setup flow to give thousand-foot view to
  users setting up Vulcanize for the first time
This commit is contained in:
James Christie 2018-08-06 10:25:31 -05:00 committed by Ian Norden
parent ba071ef13f
commit 93960e7c4e
1 changed files with 63 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
README.md
View File

@ -15,67 +15,103 @@ Vulcanize DB is a set of tools that make it easier for developers to write appli
- [Go Ethereum](https://ethereum.github.io/go-ethereum/downloads/) (1.8+)
- [Parity 1.8.11+](https://github.com/paritytech/parity/releases)
## Project Setup
Using Vulcanize for the first time requires several steps be done in order to allow use of the software. The following instructions will offer a guide through the steps of the process:
1. Fetching the project
2. Installing dependencies
3. Configuring shell environment
4. Database setup
5. Configuring synced Ethereum node integration
6. Data syncing
## Installation
In order to fetch the project codebase for local use or modification, install it to your `GOPATH` via:
`go get github.com/vulcanize/vulcanizedb`
Once fetched, dependencies can be installed via `go get` or (the preferred method) at specific versions via `golang/dep`, the prototype golang pakcage manager. Installation instructions are [here](https://golang.github.io/dep/docs/installation.html).
In order to install packages with `dep`, ensure you are in the project directory now within your `GOPATH` (default location is `~/go/src/github.com/vulcanize/vulcanizedb/`) and run:
`dep ensure`
After `dep` finishes, dependencies should be installed within your `GOPATH` at the versions specified in `Gopkg.toml`.
Lastly, ensure that `GOPATH` is defined in your shell. If necessary, `GOPATH` can be set in `~/.bashrc` or `~/.bash_profile`, depending upon your system. It can be additionally helpful to add `$GOPATH/bin` to your shell's `$PATH`.
## Setting up the Database
1. Install Postgres
1. Create a superuser for yourself and make sure `psql --list` works without prompting for a password.
1. `createdb vulcanize_public`
1. `cd $GOPATH/src/github.com/vulcanize/vulcanizedb`
1. Run the migrations: `make migrate HOST_NAME=localhost NAME=vulcanize_public PORT=5432`
1. Execute `createdb vulcanize_public`
1. Execute `cd $GOPATH/src/github.com/vulcanize/vulcanizedb`
1. Run the migrations: `make migrate HOST_NAME=localhost NAME=vulcanize_public PORT=<postgres port, default 5432>`
* See below for configuring additional environments
## Configuration
In some cases (such as recent Ubuntu systems), it may be necessary to overcome failures of password authentication from `localhost`. To allow access on Ubuntu, set localhost connections via hostname, ipv4, and ipv6 from `peer`/`md5` to `trust` in: `/etc/postgresql/<version>/pg_hba.conf`
(It should be noted that trusted auth should only be enabled on systems without sensitive data in them: development and local test databases.)
## Configuring Ethereum Node Integration
- To use a local Ethereum node, copy `environments/public.toml.example` to
`environments/public.toml` and update the `ipcPath` and `levelDbPath`.
- `ipcPath` should match the local node's IPC filepath:
- when using geth:
- For Geth:
- The IPC file is called `geth.ipc`.
- The geth IPC file path is printed to the console when you start geth.
- The default location is:
- Mac: `$HOME/Library/Ethereum`
- Linux: `$HOME/.ethereum`
- Mac: `<full home path>/Library/Ethereum`
- Linux: `<full home path>/ethereum/geth.ipc`
- when using parity:
- For Parity:
- The IPC file is called `jsonrpc.ipc`.
- The default location is:
- Mac: `$HOME/Library/Application\ Support/io.parity.ethereum/`
- Linux: `$HOME/.local/share/io.parity.ethereum/`
- Mac: `<full home path>/Library/Application\ Support/io.parity.ethereum/`
- Linux: `<full home path>/local/share/io.parity.ethereum/`
- `levelDbPath` should match Geth's chaindata directory path.
- The geth LevelDB chaindata path is printed to the console when you start geth.
- The default location is:
- Mac: `$HOME/Library/Ethereum/geth/chaindata`
- Linux: `$HOME/.ethereum/geth/chaindata`
- Mac: `<full home path>/Library/Ethereum/geth/chaindata`
- Linux: `<full home path>/ethereum/geth/chaindata`
- `levelDbPath` is irrelevant (and `coldImport` is currently unavailable) if only running parity.
- See `environments/infura.toml` to configure commands to run against infura, if a local node is unavailable
- See `environments/infura.toml` to configure commands to run against infura, if a local node is unavailable. (Support is currently experimental, at this time.)
## Start syncing with postgres
Syncs VulcanizeDB with the configured Ethereum node, populating blocks, transactions, receipts, and logs.
This command is useful when you want to maintain a broad cache of what's happening on the blockchain.
1. Start Ethereum node (**if fast syncing your Ethereum node, wait for initial sync to finish**)
1. In a separate terminal start VulcanizeDB:
- `./vulcanizedb sync --config <config.toml> --starting-block-number <block-number>`
Syncs VulcanizeDB with the configured Ethereum node.
1. Start the node
- If node state is not yet fully synced, Vulcanize will not be able to operate on the fetched data. You will need to wait for the initial sync to finish.
1. Start the vulcanize_db sync
- Execute `./vulcanizedb sync --config <path to config.toml>`
- Or to sync from a specific block: `./vulcanizedb sync --config <config.toml> --starting-block-number <block-number>`
## Alternatively, sync from Geth's underlying LevelDB
Sync VulcanizeDB from the LevelDB underlying a Geth node.
1. Assure node is not running, and that it has synced to the desired block height.
1. Start vulcanize_db
- `./vulcanizedb coldImport --config <config.toml> --starting-block-number <block-number> --ending-block-number <block-number>`
- `./vulcanizedb coldImport --config <config.toml>`
1. Optional flags:
- `--starting-block-number`/`-s`: block number to start syncing from
- `--ending-block-number`/`-e`: block number to sync to
- `--starting-block-number <block number>`/`-s <block number>`: block number to start syncing from
- `--ending-block-number <block number>`/`-e <block number>`: block number to sync to
- `--all`/`-a`: sync all missing blocks
## Alternatively, sync in "light" mode
Syncs VulcanizeDB with the configured Ethereum node, populating only block headers.
This command is useful when you want a minimal baseline from which to track targeted data on the blockchain (e.g. individual smart contract storage values).
1. Start Ethereum node
2. In a separate terminal start VulcanizeDB:
- `./vulcanizedb lightSync --config <config.toml> --starting-block-number <block-number>`
## Running the Tests
In order to run the full test suite, a test database must be prepared. By default, the rests use a database named `vulcanize_private`. Create the database in Postgres, and run migrations on the new database in preparation for executing tests:
`make migrate HOST_NAME=localhost NAME=vulcanize_private PORT=<postgres port, default 5432>`
Ginkgo is declared as a `dep` package test execution. Linting and tests can be run together via a provided `make` task:
`make test`
Tests can be run directly via Ginkgo in the project's root directory:
`ginkgo -r`
## Start full environment in docker by single command
@ -99,11 +135,3 @@ false
```
If you have full rinkeby chaindata you can move it to `rinkeby_vulcanizedb_geth_data` docker volume to skip long wait of sync.
## Running the Tests
### Unit Tests
- `go test ./pkg/...`
### Integration Tests
- `go test ./...` to run all tests.