Update README and docs

Signed-off-by: Stanislav Bogatyrev <stanislav@nspcc.ru>
This commit is contained in:
Stanislav Bogatyrev 2020-09-25 23:36:46 +03:00 committed by Stanislav Bogatyrev
parent 1a8f5bd112
commit 14430a9e00
9 changed files with 279 additions and 9 deletions

4
.env
View file

@ -9,10 +9,10 @@ NEOGO_VERSION=0.91.0-6-gd7e13de5
# NeoGo sidechain # NeoGo sidechain
MORPH_CHAIN_URL="https://fs.neo.org/dist/neo.morph.gz" MORPH_CHAIN_URL="https://fs.neo.org/dist/neo.morph.gz"
# NeoFS Storage nodes # NeoFS InnerRing nodes
IR_VERSION=0.11.0-153-g50a19cf IR_VERSION=0.11.0-153-g50a19cf
IR_IMAGE=nspccdev/neofs-ir IR_IMAGE=nspccdev/neofs-ir
# NeoFS InnerRing nodes # NeoFS Storage nodes
NODE_VERSION=0.11.0-153-g50a19cf NODE_VERSION=0.11.0-153-g50a19cf
NODE_IMAGE=nspccdev/neofs-storage NODE_IMAGE=nspccdev/neofs-storage

View file

@ -1,12 +1,16 @@
#!/usr/bin/make -f #!/usr/bin/make -f
SHELL := bash SHELL = bash
# Main environment configuration
include .env include .env
# Optional variables with secrests
-include .secrets -include .secrets
# help target
include help.mk include help.mk
# Get # Targets to get required artifacts and external resources for each service
include services/*/artifacts.mk include services/*/artifacts.mk
# Services that require artifacts # Services that require artifacts
@ -15,11 +19,11 @@ GET_SVCS = $(shell grep -Rl "get.*:" ./services/* | sort -u | grep artifacts.mk
# Services that require pulling images # Services that require pulling images
PULL_SVCS = $(shell find ./services -type f -name 'docker-compose.yml' | sort -u | xargs -I {} dirname {} | xargs basename -a) PULL_SVCS = $(shell find ./services -type f -name 'docker-compose.yml' | sort -u | xargs -I {} dirname {} | xargs basename -a)
# Sorted services for running # List of services to run
START_SVCS = $(shell cat .services | grep -v \\\#) START_SVCS = $(shell cat .services | grep -v \\\#)
STOP_SVCS = $(shell tac .services | grep -v \\\#) STOP_SVCS = $(shell tac .services | grep -v \\\#)
# List of available sites # List of hosts available in devenv
HOSTS_LINES = $(shell grep -Rl IPV4_PREFIX ./services/* | grep .hosts) HOSTS_LINES = $(shell grep -Rl IPV4_PREFIX ./services/* | grep .hosts)
@ -34,12 +38,12 @@ pull:
get: $(foreach SVC, $(GET_SVCS), get.$(SVC)) get: $(foreach SVC, $(GET_SVCS), get.$(SVC))
@: @:
# Start environments # Start environment
.PHONY: up .PHONY: up
up: get vendor/hosts up: get vendor/hosts
$(foreach SVC, $(START_SVCS), $(shell docker-compose -f services/$(SVC)/docker-compose.yml up -d)) $(foreach SVC, $(START_SVCS), $(shell docker-compose -f services/$(SVC)/docker-compose.yml up -d))
# Stop environments # Stop environment
.PHONY: down .PHONY: down
down: down:
$(foreach SVC, $(STOP_SVCS), $(shell docker-compose -f services/$(SVC)/docker-compose.yml down)) $(foreach SVC, $(STOP_SVCS), $(shell docker-compose -f services/$(SVC)/docker-compose.yml down))

View file

@ -8,7 +8,7 @@
--- ---
## Overview ## Overview
Tools to setup local NeoFS network and Neo 3 privnet. Tools to set up local NeoFS network and Neo 3 privnet. Devenv, for short.
## Quick Start ## Quick Start
@ -29,6 +29,32 @@ $ make hosts
It's recommended to add `make hosts` output to your local `/etc/hosts` file. It's recommended to add `make hosts` output to your local `/etc/hosts` file.
## How it's organized
```
.
├── Makefile # Commands to manage devenv
├── .services # List of services to work with
├── services # Services definitions and files
│   ├── basenet
│   ├── chain
│   ├── ir
│   ├── morph_chain
│   └── storage
├── vendor # Temporary files and artifacts
└── wallets # Wallet files to manage GAS assets
```
Main commands and targets to manage devenv's services are in `Makefile`.
Each service is defined in it's own directory under `services/` with all
required files to run and scripts to get external artifacts or dependencies.
The list of services and the starting order is defined in `.services` file. You
can comment out services you don't want to start or add your own new services.
You can find more information on each service in `docs` directory.
## Contributing ## Contributing
Feel free to contribute to this project after reading the [contributing Feel free to contribute to this project after reading the [contributing

38
docs/basenet.md Normal file
View file

@ -0,0 +1,38 @@
# basenet service
The `basenet` service defines the common network to use as "Internet" to let
services communicate to external world. It's a bridge network connected to the
host machine, so all programs running on host can connect to services exposed to
`basenet_internet` from devenv containers.
## .env settings
### LOCAL_DOMAIN=neofs.devenv
Domain to use for all containers exposed to `basenet_internet`.
### IPV4_PREFIX=192.168.130
IPv4 /24 subnet to use for all containers exposed to `basenet_internet`. Last
octet will be defined in `docker-compose.yml` file for each container inside
service. For simplicity, each service reserves ten host addresses.
## bastion container
There is a `bastion` container with debian 10 userspace to simplify access to
devenv services.
Run shell in bastion:
```
neofs-dev-env$ docker exec -ti bastion /bin/bash
root@bastion:/# ip a sh
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
inet 127.0.0.1/8 scope host lo
valid_lft forever preferred_lft forever
1569: eth0@if1570: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
link/ether 02:42:c0:a8:82:0a brd ff:ff:ff:ff:ff:ff link-netnsid 0
inet 192.168.130.10/24 brd 192.168.130.255 scope global eth0
valid_lft forever preferred_lft forever
```

138
docs/chain.md Normal file
View file

@ -0,0 +1,138 @@
# Neo 3 privnet service
A single-node Neo3 privnet deployment running on
[neo-go](https://github.com/nspcc-dev/neo-go).
Contracts deployed:
- NeoFS [mainnet contract](https://github.com/nspcc-dev/neofs-contract)
## .env settings
### CHAIN_URL="https://fs.neo.org/dist/devenv.gz"
URL to get main chain dump. Used on artifact get stage.
### CHAIN_PATH
Path to get main chain dump. If set, overrides `CHAIN_URL`.
### NEOGO_VERSION=0.91.0-6-gd7e13de5
Version on NeoGo container to use in both main privnet and sidechain.
## Main Privnet GAS
There is a wallet with GAS for both main privnet and side chain in
`wallets/wallet.json`.
```
$ neo-go wallet nep5 balance --token GAS \
-w wallets/wallet.json \
--addr NTrezR3C4X8aMLVg7vozt5wguyNfFhwuFx \
-r http://main_chain.neofs.devenv:30333
TokenHash: 668e0c1f9d7b70a99dd9e06eadd4c784d641afbc
Amount : 9987.92281340
Updated: 13908
```
If you need GAS to deploy contracts on main privnet or create NeoFS account by
making deposits on NeoFS mainnet contract, you can transfer GAS from that
wallet.
Create new wallet
```
$ neo-go wallet init -a -w wallets/neofs1.json
Enter the name of the account > neofs1
Enter passphrase >
Confirm passphrase >
{
"version": "3.0",
"accounts": [
{
"address": "NXnzw3J9VvKXjM1BPAJK4QUpTtEQu4TpU6",
...
wallet successfully created, file location is wallets/neofs1.json
```
Transfer some GAS there
```
$ neo-go wallet nep5 transfer --privnet -w wallets/wallet.json \
--from NTrezR3C4X8aMLVg7vozt5wguyNfFhwuFx \
--to NXnzw3J9VvKXjM1BPAJK4QUpTtEQu4TpU6 \
--amount 50 --token GAS \
--rpc-endpoint http://main_chain.neofs.devenv:30333
```
Check it's there
```
$ neo-go wallet nep5 balance --token GAS \
-w wallets/neofs1.json \
--addr NXnzw3J9VvKXjM1BPAJK4QUpTtEQu4TpU6 \
-r http://main_chain.neofs.devenv:30333
TokenHash: 668e0c1f9d7b70a99dd9e06eadd4c784d641afbc
Amount : 50
Updated: 14689
```
## Claim GAS from NEO on CN
If there is no enough GAS on `wallets/wallet.json` account, you can claim some
GAS from CN node's wallet from `services/chain/node-wallet.json` and then
transfer it. Wallet password can be found in
`services/chain/protocol.privnet.yml` file.
```
$ neo-go wallet claim -w services/chain/node-wallet.json \
-a NVNvVRW5Q5naSx2k2iZm7xRgtRNGuZppAK \
-r http://main_chain.neofs.devenv:30333
Password >
70e09bbd55846dcc7cee23905b737c63e5a80d32e387bce108bc6db8e641fb90
```
Then you can transfer GAS the same way as it was done in previous section.
```
neo-go wallet nep5 transfer --privnet -w services/chain/node-wallet.json \
--from NVNvVRW5Q5naSx2k2iZm7xRgtRNGuZppAK \
--to NXnzw3J9VvKXjM1BPAJK4QUpTtEQu4TpU6 \
--amount 500 --token GAS \
--rpc-endpoint http://main_chain.neofs.devenv:30333
```
## NeoFS GAS deposit
NeoFS identifies users by their Neo wallet key pair. To start using NeoFS in
devenv you need to transfer some GAS from Main privnet account to NeoFS main
contract's account by calling the `deposit` method.
First you need to get your account's LE encoded ScriptHash
```
$ neo-go util convert NXnzw3J9VvKXjM1BPAJK4QUpTtEQu4TpU6
Address to BE ScriptHash 82500e2e7de441e1b7378146ad91474f30fa1a0b
Address to LE ScriptHash 0b1afa304f4791ad468137b7e141e47d2e0e5082
Address to Base64 (BE) glAOLn3kQeG3N4FGrZFHTzD6Ggs=
Address to Base64 (LE) Cxr6ME9Hka1GgTe34UHkfS4OUII=
String to Hex 4e586e7a77334a3956764b586a4d314250414a4b3451557054744551753454705536
String to Base64 TlhuenczSjlWdktYak0xQlBBSks0UVVwVHRFUXU0VHBVNg==
```
And call the `deposit` method:
```
$ neo-go contract invokefunction -w wallets/neofs1.json \
-a NXnzw3J9VvKXjM1BPAJK4QUpTtEQu4TpU6 \
-r http://main_chain.neofs.devenv:30333 \
af5dc5f7e6a6efc64d679098f328027591a2e518 \
deposit 0b1afa304f4791ad468137b7e141e47d2e0e5082 \
int:50 bytes: -- 0b1afa304f4791ad468137b7e141e47d2e0e5082
Enter account NXnzw3J9VvKXjM1BPAJK4QUpTtEQu4TpU6 password >
Sent invocation transaction 50e25f8e85c3b52dbd99381104cbe8056dad1a6e8809e8bf0e5d0a2527f55932
```

17
docs/faq.md Normal file
View file

@ -0,0 +1,17 @@
# F.A.Q, tips and tricks
### How to see what's inside running container if there's no shell?
You can run any program in container's namespace using `nsenter` utility.
```
$ docker inspect -f '{{.State.Pid}}' fs.neo.org
27242
$ sudo nsenter -t 27242 -n netstat -antp
Active Internet connections (servers and established)
Proto Recv-Q Send-Q Local Address Foreign Address State PID/Program name
tcp 0 0 127.0.0.11:43783 0.0.0.0:* LISTEN 1376/dockerd
tcp6 0 0 :::443 :::* LISTEN 27242/nginx: master
tcp6 0 0 :::80 :::* LISTEN 27242/nginx: master
```

16
docs/ir.md Normal file
View file

@ -0,0 +1,16 @@
# NeoFS Inner Ring
Minimal set of seven NeoFS InnerRing as required by Governance scheme.
## .env settings
### IR_VERSION=0.11.0-153-g50a19cf
Image version label to use for InnerRing containers.
If you want to use locally built image, just set it's label here. Instead of
pulling from DockerHub, the local image will be used.
### IR_IMAGE=nspccdev/neofs-ir
Image label prefix to use for InnerRing containers.

18
docs/morph.md Normal file
View file

@ -0,0 +1,18 @@
# NeoFS sidechain service
It's a single-node Neo3-based NeoFS sidechain deployment running on
[neo-go](https://github.com/nspcc-dev/neo-go).
## .env settings
### MORPH_CHAIN_URL="https://fs.neo.org/dist/neo.morph.gz"
URL to get NeoFS sidechain dump. Used on artifact get stage.
### MORPH_CHAIN_PATH
Path to get NeoFS sidechain chain dump. If set, overrides `MORPH_CHAIN_URL`.
### NEOGO_VERSION=0.91.0-6-gd7e13de5
Version on NeoGo container to use in both main privnet and sidechain.

13
docs/storage.md Normal file
View file

@ -0,0 +1,13 @@
# Storage nodes service
## .env settings
### NODE_VERSION=0.11.0-153-g50a19cf
Image version label to use for Storage Node containers.
If you want to use locally built image, just set it's label here. Instead of
pulling from DockerHub, the local image will be used.
### NODE_IMAGE=nspccdev/neofs-ir
Image label prefix to use for Storage containers.