Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

update docs based on new PR with LOTUS_MARKETS_PATH #982

Merged
merged 6 commits into from
Aug 2, 2021
Merged

update docs based on new PR with LOTUS_MARKETS_PATH #982

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0ff243a
update docs based on new PR with LOTUS_MARKETS_PATH
nonsense Jul 29, 2021
21a1cc5
fixup
nonsense Jul 29, 2021
0489fce
fixup
nonsense Jul 29, 2021
7f5eb64
fixed typos and directories
nonsense Jul 29, 2021
9eac364
fixup
nonsense Jul 29, 2021
8672576
fixup
nonsense Jul 30, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 53 additions & 31 deletions docs/mine/lotus/split-markets-miners.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,12 +57,12 @@ This document explains how to split your existing monolith `lotus-miner` node in
Before splitting the markets service process from the monolith miner process, you should backup your miner's metadata repository. You need to start the `lotus-miner` with the `LOTUS_BACKUP_BASE_PATH` env variable in order to do that.

```shell
export LOTUS_BACKUP_BASE_PATH=~/lotus-backup-location
export LOTUS_BACKUP_BASE_PATH=/tmp
lotus daemon
```

```shell
export LOTUS_BACKUP_BASE_PATH=~/lotus-backup-location
export LOTUS_BACKUP_BASE_PATH=/tmp
lotus-miner run
```

Expand All @@ -71,15 +71,15 @@ lotus-miner run
### 1. Creating a backup

```shell
export LOTUS_BACKUP_BASE_PATH=~/lotus-backup-location
lotus-miner backup ~/lotus-backup-location/backupfile
export LOTUS_BACKUP_BASE_PATH=/tmp
lotus-miner backup /tmp/backup.cbor
```

### 2. Create `config.toml` for the markets service

You need to create a `config.toml` for the markets node, and have it ready for the next step. For more information see [configuration usage page](https://docs.filecoin.io/get-started/lotus/configuration-and-advanced-usage/) and the [custom storage layout page](https://docs.filecoin.io/mine/lotus/custom-storage-layout/).
You need to create a seed `config.toml` for the markets node, and have it ready for the next step. For more information see [configuration usage page](https://docs.filecoin.io/get-started/lotus/configuration-and-advanced-usage/) and the [custom storage layout page](https://docs.filecoin.io/mine/lotus/custom-storage-layout/).

In the example commands below, we have placed the `config.toml` in the `~/.lotusmarket` directory, which is not the repository directory for the `markets` instance. The repository directory which we use is `~/markets-repo-location`. We are using the following `config.toml`:
In the example commands below, we have placed the `config.toml` in the `/tmp` directory. The repository directory which we use is `~/.lotusmarkets`. We are using the following `config.toml`:

```toml
[API]
Expand All @@ -99,11 +99,11 @@ The `[Libp2p]` section on the `mining/sealing/proving` node can be removed becau

### 3. Initialising a `markets` service repository

1. Create authentication tokens for the `markets` node
1. Create authentication tokens for the `markets` node. This is an online operation, so your `lotus-miner` should be running with its updated configuration (in case you move its API to another IP:PORT)

```shell
export APISEALER=`./lotus-miner auth api-info --perm=admin`
export APISECTORINDEX=`./lotus-miner auth api-info --perm=admin`
export APISEALER=`lotus-miner auth api-info --perm=admin`
export APISECTORINDEX=`lotus-miner auth api-info --perm=admin`
```

2. Initialise the `market` node. This performs a one-time setup of the markets node. Part of that setup includes updating the `peer id` in the miner actor by submitting a message on chain. This is necessary so that storage and retrieval clients know that this miner's **deal-making** endpoint is now publicly dialable/reachable on a new address (the new `market` node).
Expand All @@ -113,25 +113,23 @@ Note that `lotus-miner` interacts with one repository or another depending on th
This command should be run on the `markets` miner instance host, as it is creating the `markets` miner instance repository, among other actions.

```shell
export LOTUS_MINER_PATH=~/markets-repo-location

./lotus-miner init service --type=markets \
--api-sealer=$APISEALER \
--api-sector-index=$APISECTORINDEX \
--config=~/.lotusmarket/config.toml \
~/lotus-backup-location/backupfile
lotus-miner --markets-repo=~/.lotusmarkets init service --type=markets \
--api-sealer=$APISEALER \
--api-sector-index=$APISECTORINDEX \
--config=/tmp/config.toml \
/tmp/backup.cbor
```

3. Optionally update your miner's `multiaddr` on-chain - in case your `markets` instance is publicly exposed at a different location compared to your exiting monolith miner, you also need to update your `multiaddr` on-chain and advertise the correct one to clients:
3. Optionally update your miner's `multiaddr` on-chain - in case your `markets` instance is publicly exposed at a different location compared to your existing monolith miner, you also need to update your `multiaddr` on-chain and advertise the correct one to clients:

```shell
./lotus-miner actor set-addrs <NEW_MULTIADDR>
lotus-miner actor set-addrs <NEW_MULTIADDR>
```

### 4. Move the DAG store directory to the markets node repository

```shell
mv ~/.lotusminer/dagStore ~/markets-repo-location/
mv ~/.lotusminer/dagStore ~/.lotusmarkets/
```

### 5. Start the `mining/sealing/proving` miner process without the markets subsystem
Expand All @@ -141,34 +139,58 @@ mv ~/.lotusminer/dagStore ~/markets-repo-location/
2. Start the node (with the default LOTUS_MINER_PATH, which should point to your `mining/sealing/proving` node repo). Note that `lotus-miner` interacts with a given repository depending on the `LOTUS_MINER_PATH` environment variable!

```shell
./lotus-miner run
lotus-miner run
```

### 6. Start the `markets` miner process with the markets subsystem

```shell
LOTUS_MINER_PATH=~/markets-repo-location ./lotus-miner run
LOTUS_MINER_PATH=~/.lotusmarkets lotus-miner run
```

## Interacting with the different miner instances with CLI over JSON RPC

> In case you run more than one miner instance on the same machine, make sure that you have `MINER_API_INFO` environment variable `unset`. If you have it set, you will always be interacting with only one miner process, because it has precedence over `LOTUS_MINER_PATH`.
The client-side CLI commands have been refactored to target the correct `lotus-miner` node, depending on issued command. For example:

1. If you call `lotus-miner storage-deals list`, `lotus-miner` *knows* to target the `markets` process.
1. If you call `lotus-miner sectors list`, `lotus-miner` *knows* to target the `mining/sealing/proving` process.

If a given CLI is supported by all miner types, by default it targets the `mining/sealing/proving` process, but you can target the `markets` process with the `--call-on-markets` flag.

In order to take advantage of this functionality, You should configure the following environment variable for the `mining/sealing/proving` miner and the `markets` miner, in your run-commands file (`.bashrc`, `.zshrc`, etc.):

```shell
export LOTUS_MARKETS_PATH=~/.lotusmarkets
export LOTUS_MINER_PATH=~/.lotusminer
```

If one of these nodes is on a remote machine, you should set the relevant API_INFO environment variables, for example:

```shell
export MARKETS_API_INFO=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.7wPg1b8C-yigqgoCUL-62gzOCZAVjb6mrvnaE8W27OI:/ip4/127.0.0.1/tcp/2345/http
export MINER_API_INFO=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.m3aKgJDsJBVePHWAPpy5aDMaWZ7ZMV9rqe_8MokTwgY:/ip4/127.0.0.1/tcp/8787/http
```

Now that you have both a `markets` miner process and a `mining/sealing/proving` miner process running, you can confirm that you can interact with each respective process with the following:

1. Get miner info
```shell
lotus-miner info
```

1. Get the peer identity of the `markets` miner process
```shell
LOTUS_MINER_PATH=~/markets-repo-location ./lotus-miner net id
lotus-miner --call-on-markets net id
```

2. Get a list of storage deals from the `markets` miner process
```shell
LOTUS_MINER_PATH=~/markets-repo-location ./lotus-miner storage-deals list
lotus-miner storage-deals list
```

3. Get a list of sectors from the `mining/sealing/proving` miner process
```shell
LOTUS_MINER_PATH=~/.lotusminer ./lotus-miner sectors list
lotus-miner sectors list
```

## Rollback to `lotus-miner` monolith process
Expand All @@ -189,33 +211,33 @@ If you want to revert the changes listed above and go back to running `lotus-min
3. Move back the DAG store directory to the monolith miner node repository

```shell
mv ~/markets-repo-location/dagStore ~/.lotusminer/
mv ~/.lotusmarkets/dagStore ~/.lotusminer/
```

4. Backup and restore the metadata related to storage deals from the `markets` instance back to the monolith miner instance. Given that storage deals metadata would have changed on the `markets` instance in case you accepted storage deals while running multi-services architecture, we have to copy it back to the monolith miner instance.

```shell
./lotus-shed market export-datastore --repo ~/markets-repo-location --backup-dir /tmp/deals-backup
lotus-shed market export-datastore --repo ~/.lotusmarkets --backup-dir /tmp/deals-backup

./lotus-shed market import-datastore --repo ~/.lotusminer --backup-path /tmp/deals-backup/markets.datastore.backup
lotus-shed market import-datastore --repo ~/.lotusminer --backup-path /tmp/deals-backup/markets.datastore.backup
```

5. Restart the `mining/sealing/proving` node (with the default LOTUS_MINER_PATH, which should point to your `mining/sealing/proving` node repo). Note that `lotus-miner` interacts with a given repository depending on the `LOTUS_MINER_PATH` environment variable!

```shell
./lotus-miner run
lotus-miner run
```

6. Fetch the node identity. This is necessary as you have to update your miner's peer identity on-chain, as it was changed to the identity of the markets node during the initialising of the markets service repository.

```shell
./lotus-miner net id
lotus-miner net id
```

7. Update the miner's peer id on-chain with the result from the previous step.

```shell
./lotus-miner actor set-peer-id 12D3XXXXX
lotus-miner actor set-peer-id 12D3XXXXX
```

As soon as the message is confirmed, clients will know to look for the node identity of your `mining/sealing/proving` node, which now also runs the `markets` subsystem, i.e. currently all Lotus subsystems.
Expand Down