diff --git a/docs/cli-adm.md b/docs/cli-adm.md index c183dfa651..736825b134 100644 --- a/docs/cli-adm.md +++ b/docs/cli-adm.md @@ -104,4 +104,4 @@ info. These commands **do not migrate actual objects**. ## Private network deployment -Read step-by-step guide of private storage deployment [in docs](./deploy.md). +Read step-by-step guide of private storage deployment [in docs](deploy.md). diff --git a/docs/deploy.md b/docs/deploy.md index 357028c717..2ed236c067 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -1,29 +1,32 @@ # Step-by-step private NeoFS deployment -This is a short guide on how to deploy a private NeoFS storage network on bare -metal without docker images. This guide does not cover details on how to start -consensus, Alphabet, or Storage nodes. This guide covers only `neofs-adm` -related configuration details. +This guide describes the current bare-metal setup flow for a private NeoFS +network. The basic workflow is intentionally simple: generate a network config, +create the required wallets with `neofs-adm`, start the N3/Alphabet nodes, then +bring up a Storage node and trigger a new epoch. + +This document focuses on the `neofs-adm` part of the deployment. It does not +cover every node startup detail, but it does cover the configuration and wallet +steps that are required for a private installation. ## Prerequisites To follow this guide you need: -- latest released version of [neo-go](https://github.com/nspcc-dev/neo-go/releases) (v0.97.2 at the moment), -- latest released version of [neofs-adm](https://github.com/nspcc-dev/neofs-node/releases) utility (v0.25.1 at the moment), -- latest released version of compiled [neofs-contract](https://github.com/nspcc-dev/neofs-contract/releases) (v0.11.0 at the moment). -## Step 1: Prepare network configuration +- a recent release of [neo-go](https://github.com/nspcc-dev/neo-go/releases) +- a recent release of [neofs-adm](https://github.com/nspcc-dev/neofs-node/releases) +- the compiled NeoFS contracts from the latest [neofs-contract](https://github.com/nspcc-dev/neofs-contract/releases) release -To start a network, you need a set of consensus nodes, the same number of -Alphabet nodes and any number of Storage nodes. While the number of Storage -nodes can be scaled almost infinitely, the number of consensus and Alphabet -nodes can't be changed so easily right now. Consider this before going any further. +## Step 1: Prepare the network configuration -It is easier to use`neofs-adm` with a predefined configuration. First, create -a network configuration file. In this example, there is going to be only one -consensus / Alphabet node in the network. +A private network usually has a set of N3 consensus nodes, the same number of +Alphabet nodes, and any number of Storage nodes. The number of Storage nodes can +be scaled as needed, but the number of consensus and Alphabet nodes is chosen at +network setup time and should be planned ahead. -``` +Create a config file with `neofs-adm` first: + +```bash $ neofs-adm config init --path foo.network.yml Initial config file saved to foo.network.yml @@ -37,114 +40,68 @@ network: fee: candidate: 0 container: 0 + container_alias: 0 withdraw: 0 credentials: az: hunter2 ``` -For private installation, it is recommended to set all **fees** and **basic -income rate** to 0. +For a private installation, all network fees and the basic income rate are +usually set to `0`. -As for **epoch duration**, consider consensus node block generation frequency. -With default 15 seconds per block, 240 blocks are going to be a 1-hour epoch. +The epoch duration is measured in blocks. For example, a value of `240` +corresponds to 240 blocks; with a 15-second block time this is roughly one hour. -For **max object size**, 67108864 (64 MiB) or 134217728 (128 MiB) should provide -good chunk distribution in most cases. +For the maximum object size, 64 MiB is the default and the recommended choice +for a private test or development network. -With this config, generate wallets (private keys) of consensus nodes. The same -wallets will be used for Alphabet nodes. Make sure, that dir for alphabet -wallets already exists. +## Step 2: Generate the Alphabet wallet set -``` +The same wallets are used for the consensus and Alphabet roles. `neofs-adm` +creates the needed accounts and multisig entries automatically: + +```bash $ neofs-adm -c foo.network.yml fschain generate-alphabet --size 1 size: 1 alphabet-wallets: /home/user/deploy/alphabet-wallets wallet[0]: hunter2 ``` -Do not lose wallet files and network config. Store it in an encrypted backed up -storage. - -## Step 2: Launch consensus nodes - -Configure blockchain nodes with the generated wallets from the previous step. -Config examples can be found in -[neo-go repository](https://github.com/nspcc-dev/neo-go/tree/master/config). - -Gather public keys from **all** generated wallets. We are interested in the first -`simple signature contract` public key. - -``` -$ neo-go wallet dump-keys -w alphabet-wallets/az.json -NitdS4k4f1Hh5mbLJhAswBK3WC2gQgPN1o (simple signature contract): -02c1cc85f9c856dbe2d02017349bcb7b4e5defa78b8056a09b3240ba2a8c078869 - -NiMKabp3ddi3xShmLAXhTfbnuWb4cSJT6E (1 out of 1 multisig contract): -02c1cc85f9c856dbe2d02017349bcb7b4e5defa78b8056a09b3240ba2a8c078869 - -NiMKabp3ddi3xShmLAXhTfbnuWb4cSJT6E (1 out of 1 multisig contract): -02c1cc85f9c856dbe2d02017349bcb7b4e5defa78b8056a09b3240ba2a8c078869 -``` - -Put the list of public keys into `ProtocolConfiguration.StandbyCommittee` -section. Specify the wallet path and the password in `ApplicationConfiguration.P2PNotary` -and `ApplicationConfiguration.UnlockWallet` sections. +Keep the wallet files and the network config in a safe place. Losing them means +losing access to the private network state. -```yaml -ProtocolConfiguration: - StandbyCommittee: - - 02c1cc85f9c856dbe2d02017349bcb7b4e5defa78b8056a09b3240ba2a8c078869 -ApplicationConfiguration: - P2PNotary: - Enabled: true - UnlockWallet: - Path: "/home/user/deploy/alphabet-wallets/az.json" - Password: "hunter2" - UnlockWallet: - Path: "/home/user/deploy/alphabet-wallets/az.json" - Password: "hunter2" -``` +## Step 3: Launch the consensus and Alphabet nodes -Then, launch consensus nodes. They should connect to each other and start -producing blocks in consensus. You might want to deploy additional RPC -nodes at this stage because Storage nodes should be connected to the chain too. -It is not recommended to use a consensus node as an RPC node due to security policies -and possible overload issues. +The generated wallets are then used to configure the N3 consensus nodes and the +Alphabet nodes. -## Step 3: Launch Alphabet nodes +The command output from `generate-alphabet` includes the wallet password. Use the +wallets from `alphabet-wallets` to populate the consensus configuration, and use +those same public keys for the `ProtocolConfiguration.StandbyCommittee` and +`fschain.validators` settings. For the actual IR and node config examples, use +the files shipped in this repository, such as `config/example/ir.yaml` and +`config/example/node.yaml`. -Configure Alphabet nodes with the wallets generated in step 1. For -`fschain.validators` use a list of public keys from -`ProtocolConfiguration.StandbyCommittee`. +At this point, the consensus nodes should connect to each other and start +producing blocks. Additional dedicated RPC endpoints are recommended for storage +nodes, because using a consensus node for RPC traffic is not good practice for a +production-like setup. -```yaml -wallet: - path: "/home/user/deploy/alphabet-wallets/az.json" - password: "hunter2" - account: "NitdS4k4f1Hh5mbLJhAswBK3WC2gQgPN1o" - -fschain: - validators: - - 02c1cc85f9c856dbe2d02017349bcb7b4e5defa78b8056a09b3240ba2a8c078869 -``` - -## Step 4: Launch Storage node +## Step 4: Generate a storage wallet -Generate a new wallet for a Storage node. +Create a wallet for the Storage node and fund it for bootstrap: -``` +```bash $ neofs-adm -c foo.network.yml fschain generate-storage-wallet --storage-wallet ./sn01.json --initial-gas 10.0 New password > Waiting for transactions to persist... - -$ neo-go wallet dump-keys -w sn01.json -Ngr7p8Z9S22XDH6VkUG9oXobv8zZRAWwwv (simple signature contract): -0355eccb72cd46f09a3e5237eaa0f4949cceb5ecfa5a225bd3bb9fd021c4d75b85 ``` -Configure the Storage node to use this wallet. +The generated wallet file can then be used by the Storage node configuration. +The storage node wallet should have enough GAS to register itself in the network; +see the `neofs-dev-env` or `neofs-aio` examples for a working bootstrap setup. -``` +```yaml node: wallet: path: "/home/user/deploy/sn01.json" @@ -152,16 +109,16 @@ node: password: "foobar" ``` -The storage node will be included in the network map in the next NeoFS epoch. To -speed up this process, you can increment epoch counter immediately. +## Step 5: Start the Storage node and activate it -``` +Once the Storage node is configured, start it and wait for it to register in the +network map. If you want it to appear in the next epoch immediately, trigger a +new epoch: + +```bash $ neofs-adm -c foo.network.yml fschain force-new-epoch Current epoch: 8, increase to 9. Waiting for transactions to persist... ``` ---- - -After that, NeoFS Storage is ready to work. You can access it directly or -with protocol gates. +After that, the private NeoFS Storage deployment is ready to serve requests.