Update README and docs

Signed-off-by: Stanislav Bogatyrev <stanislav@nspcc.ru>

.env

@@ -9,10 +9,10 @@ NEOGO_VERSION=0.91.0-6-gd7e13de5
 # NeoGo sidechain
 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_IMAGE=nspccdev/neofs-ir
 
-# NeoFS InnerRing nodes
+# NeoFS Storage nodes
 NODE_VERSION=0.11.0-153-g50a19cf
 NODE_IMAGE=nspccdev/neofs-storage

Makefile

@@ -1,12 +1,16 @@
 #!/usr/bin/make -f
-SHELL := bash
+SHELL = bash
 
+# Main environment configuration
 include .env
+
+# Optional variables with secrests
 -include .secrets
 
+# help target
 include help.mk
 
-# Get
+# Targets to get required artifacts and external resources for each service
 include services/*/artifacts.mk
 
 # 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
 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 \\\#)
 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)
 
 
@@ -34,12 +38,12 @@ pull:
 get: $(foreach SVC, $(GET_SVCS), get.$(SVC))
 	@:
 
-# Start environments
+# Start environment
 .PHONY: up
 up: get vendor/hosts
 	$(foreach SVC, $(START_SVCS), $(shell docker-compose -f services/$(SVC)/docker-compose.yml up -d))
 
-# Stop environments
+# Stop environment
 .PHONY: down
 down:
 	$(foreach SVC, $(STOP_SVCS), $(shell docker-compose -f services/$(SVC)/docker-compose.yml down))

README.md

@@ -8,7 +8,7 @@
 ---
 ## 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
 
@@ -29,6 +29,32 @@ $ make hosts
 
 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
 
 Feel free to contribute to this project after reading the [contributing

docs/basenet.md

@@ -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
+```

docs/chain.md

@@ -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
+```

docs/faq.md

@@ -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
+```

docs/ir.md

@@ -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.

docs/morph.md

@@ -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.

docs/storage.md

@@ -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.