Skip to content

Commit

Permalink
Update pulsar.mdx (#285)
Browse files Browse the repository at this point in the history 
* Update pulsar.mdx

Reorganized page into Quick Start, Troubleshooting and Advanced Settings sections. Makr installation more clear for first-time users.


____________________________________________________________________________
Co-authored-by: Emil Fattakhov <66026548+EmilFattakhov@users.noreply.github.com>
  • Loading branch information
@skylordafk
skylordafk committed Oct 23, 2023
1 parent b9847b1 commit e7f7e67
Showing 1 changed file with 131 additions and 147 deletions.
278 changes: 131 additions & 147 deletions versioned_docs/version-latest/protocol/pulsar.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,19 +19,12 @@ import styles from '@site/src/pages/index.module.css';
[Pulsar](https://github.com/subspace/pulsar) (previously Subspace CLI or Simple CLI) is the recommended way to farm on the Subspace Network. To get started, follow the guide below. For more information, you can check out the project [README on GitHub](https://github.com/subspace/pulsar/blob/main/README.md).
:::

## Pre-Requisites
## Quick Start

---

### System Requirements

:::danger Farming can be Network Intensive.

Make sure you have a stable network connection. During the plotting phase of farming, it can be network intensive.

This may impact your network usage so please check your network connection if you have a hard data limit.
:::

Pulsar requires commodity hardware specs to operate. At a **minimum**, it is recommended to have:

| Hardware | Specs |
Expand Down Expand Up @@ -88,58 +81,42 @@ sudo tune2fs -E stride=8,stripe-width=8 /path/to/dev

:::

## Step 1: Creating A Crypto Wallet

### Getting A Crypto Wallet

Before running anything you need to have a wallet where you'll receive testnet coins.
Follow our how-to guides in the [Wallets section](/docs/category/wallets/) of the documentation for steps on how to get your wallet setup.

### Required ports

Currently, a few ports need to be exposed for node to work properly.

If you have a server with no firewall, there is nothing to be done, but otherwise make sure to open the following TCP ports for incoming connections.

- `30333`
- `30433`
- `30533`

On the desktop side if you have a router in front of your computer, you'll need to forward TCP ports to the machine on which your node is running (how this is done varies from router to router, but there is always a feature like this, refer to [How to Forward Ports](port-forwarding.md) for a more in-depth tutorial).
If you're connected directly without any router, then again nothing needs to be done in such case.

The first thing you will need to start is a wallet to receive your farming rewards.
Follow our how-to guides in the [Wallets section](/docs/category/wallets/) of the documentation for steps on how to setup your wallet.


## Installation
## Step 2: Installation

:::caution ALPHA SOFTWARE
Pulsar is in **alpha**.
Please feel free to file bug reports on our GitHub issues.
:::
<details>
<summary>
Prefer A video? Expand for our installation video
Prefer a video? Expand this section to view the installation video.
</summary>
<div>
<iframe width="560" height="315" src="https://www.youtube.com/embed/h1-CX7lGl2w" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>
</details>


### Download Binaries

### Download Pulsar


---

Precompiled versions of the Pulsar is [hosted on GitHub](https://github.com/subspace/pulsar/releases). This is the recommended way to install the application. Please find the appropriate binary for your operating system.
Precompiled versions of Pulsar are [hosted on GitHub](https://github.com/subspace/pulsar/releases). This is the recommended way to install the application. Please find the appropriate binary for your operating system.

<Tabs groupId="OS">

<TabItem value="windows" label="🖼️ Windows" default>

:::caution

Some older processors/VMs are no longer supported by official releases, but can still be compiled manually if desired
Some older processors/VMs are no longer supported by official releases, but can still be [compiled manually](https://github.com/subspace/subspace/blob/main/docs/development.md).

:::
1. Download the Release Binary below.
Expand Down Expand Up @@ -175,9 +152,10 @@ Some older processors/VMs are no longer supported by official releases, but can

2. Open Powershell, type `cd Downloads` (or `cd Your-File-Location`).

:::warning
The warning below may appear because the application is trying to access the internet. This is expected as it is how the farmer talks to other farmers on the network. Please select 'Allow access' to continue farming.
:::warning Warning
The warning below may appear because the application is trying to access the internet. This is expected as it is how the farmer talks to other farmers on the network. Select 'Allow access' to continue farming.
:::

![Windows Defender Firewall](/img/doc-imgs/Windows_Security_Alert.png)

</TabItem>
Expand All @@ -186,7 +164,7 @@ The warning below may appear because the application is trying to access the int

:::caution

Some older processors/VMs are no longer supported by official releases, but can still be compiled manually if desired
Some older processors/VMs are no longer supported by official releases, but can still be [compiled manually](https://github.com/subspace/subspace/blob/main/docs/development.md).

:::
1. Download your Release Binary below.
Expand Down Expand Up @@ -232,7 +210,7 @@ Your Mac may not let you open/initialize the file because of unidentified develo

:::caution

Some older processors/VMs are no longer supported by official releases, but can still be compiled manually if desired
Some older processors/VMs are no longer supported by official releases, but can still be compiled manually.

:::
1. Download your Release Binary below.
Expand Down Expand Up @@ -289,11 +267,11 @@ Some older processors/VMs are no longer supported by official releases, but can

</Tabs>

### Configuration
## Step 3: Configuration

---

To start we have to initialize our Farmer, this can be done with:
Our next step is to initialize our Farmer, this can be done by running the command below:

<Tabs groupId="OS">
<TabItem value="windows" label="🖼️ Windows" default>
Expand All @@ -302,12 +280,6 @@ To start we have to initialize our Farmer, this can be done with:
./pulsar-windows-x86_64-skylake-v0.6.14-alpha.exe init
```

:::note High RAM consumption
Operating systems, such as Windows, allocate memory for both visible tasks and behind-the-scenes processes.
While this memory can be readily freed when necessary, Windows occasionally may not display these allocations accurately due to certain system nuances.
High RAM consumption should not be a cause for concern.
:::

</TabItem>

<TabItem value="macos" label="🍎 macOS">
Expand Down Expand Up @@ -339,7 +311,7 @@ Ubuntu Executable (aarch64):
</TabItem>
</Tabs>

This will prompt you to setup your Pulsar configurations to begin farming. You should see a similar prompt like so (some info might be different than shown here w.r.t your OS):
This will prompt you to configure your Pulsar settings for farming. You should see a similar prompt to the one below (some info might be different than shown here w.r.t your OS):

```text
version: 0.6.0
Expand All @@ -357,61 +329,7 @@ Configuration has been generated at /home/username/.config/pulsar
Ready for lift off! Run the follow command to begin: `"path/to/executable" farm`
```

:::info Finding your settings.toml

After running `pulsar init`, the prompt will display where the `settings.toml` is generated. However in case you missed it, you can find the file based on your operating system:

<Tabs groupId="OS">
<TabItem value="windows" label="🖼️ Windows" default>

Your `settings.toml` will be found in `$FOLDERID_RoamingAppData/pulsar/settings.toml`

</TabItem>

<TabItem value="macos" label="🍎macOS">

Your `settings.toml` will be found in `$HOME/Library/Application Support/pulsar/settings.toml`

</TabItem>

<TabItem value="linux" label="🐧Ubuntu">

Your `settings.toml` will be found in `$HOME/.config/pulsar/settings.toml`

</TabItem>
</Tabs>

:::

### Gemini 3 Testnet

---

If you are using the default configurations from Pulsar, you are ready to go with the Gemini 3 Testnet. Alternatively, you can ensure this occurs by manually setting the network like so.

Open your `settings.toml` directory and ensure your `chain` is correctly specified to `gemini-3f` as so:

```toml
# settings.toml
[node]
chain = 'gemini-3f'
# ... redacted ...
```

### Local Development

---

To run Pulsar in a local development mode, modify your `settings.toml` and ensure your `chain` points to `dev`:

```toml
# settings.toml
[node]
chain = 'dev'
# ... redacted ...
```

## Farming
## Step 4: Farming

---

Expand Down Expand Up @@ -471,7 +389,111 @@ Initial plotting for plot: #0 (/home/username/.local/share/pulsar/farms)

That's it! Enjoy and Happy Farming!

#### Moving the Farming Process to the Background

## Troubleshooting

---

### Required ports

Currently, a few ports need to be exposed for node to work properly.

If you have a server with no firewall, there is nothing to be done, but otherwise make sure to open the following TCP ports for incoming connections.

- `30333`
- `30433`
- `30533`

On the desktop side if you have a router in front of your computer, you'll need to forward TCP ports to the machine on which your node is running (how this is done varies from router to router, but there is always a feature like this, refer to [How to Forward Ports](port-forwarding.md) for a more in-depth tutorial).
If you're connected directly without any router, then again nothing needs to be done in such case.


### Inspecting Pulsar Logs

A good place to start if you are facing trouble is by viewing your logs and seeing if there are any errors or insights that might be available. You can find the location for your logs below

<Tabs groupId="OS">
<TabItem value="windows" label="🖼️ Windows" default>

Your Logs will be found in `%USERPROFILE%/AppData/Local/pulsar/logs`

</TabItem>

<TabItem value="macos" label="🍎macOS">

Your Logs will be found in `$HOME/Library/Logs/pulsar/`

</TabItem>

<TabItem value="linux" label="🐧Ubuntu">

Your Logs will be found in `$HOME/.local/share/pulsar/logs`

</TabItem>
</Tabs>


### Wipe Node & Farmer

:::tip Updated from a previous version and now having issues?

Occasionally after updating to a new version of the Pulsar you will need to wipe your node and farmer, generally this should not be required but can be attempted if your farmer is having issues after having had worked fine previously.

:::

To simply restart the node, go to the terminal where you started the `farm` command, and press `Ctrl + C` you should see a shutdown message appear and the application will attempt a simple shutdown, if you dont see the message press `Ctrl + C` again to force shutdown. You can then simply start the farmer again with the `farm` command you used prior.

Use the same file name as the previous init and farm steps, then add the wipe command to free the previous storage that was being used. Generally, only do this if you have severe errors and are prompted by a staff member.

```shell-session
./pulsar-file-name wipe
```

After wiping, follow the `init` and `farm` steps above to start farming again!


:::info Finding your settings.toml

After running `pulsar init`, the prompt will display where the `settings.toml` is generated. However in case you missed it, you can find the file based on your operating system:

<Tabs groupId="OS">
<TabItem value="windows" label="🖼️ Windows" default>

Your `settings.toml` will be found in `$FOLDERID_RoamingAppData/pulsar/settings.toml`

</TabItem>

<TabItem value="macos" label="🍎macOS">

Your `settings.toml` will be found in `$HOME/Library/Application Support/pulsar/settings.toml`

</TabItem>

<TabItem value="linux" label="🐧Ubuntu">

Your `settings.toml` will be found in `$HOME/.config/pulsar/settings.toml`

</TabItem>
</Tabs>

:::



### Still having trouble with your farmer?

If you are facing issues with your node/farmer you can try a few of the following things below, if you are unable to get your issue resolved please check our [forum](https://forums.subspace.network) to see if your issue may have already been solved, if it's a new one feel free to post it! You can also join our [Discord](https://discord.gg/subspace-network) for additional Peer to Peer help.

:::info

We have included a few tutorials below that may help you in your support journey, this is not an all inclusive list but we welcome contributions

:::


## Advanced settings

### Moving the Farming Process to the Background

<Tabs groupId="OS">
<TabItem value="tmux" label="Tmux" default>
Expand Down Expand Up @@ -546,58 +568,20 @@ $ screen -S farming -X quit
</TabItem>
</Tabs>

## Having Trouble?

If you are facing issues with your node/farmer you can try a few of the following things below, if you are unable to get your issue resolved please check our [Forums](https://forums.subspace.network) to see if your issue may have been solved, if its a new one feel free to post it! You can also join our [Discord](https://discord.gg/subspace-network) for additional Peer to Peer help.

:::info

We have included a few tutorials below that may help you in your support journey, this is not an all inclusive list but we welcome contributions

:::

### Wipe Node & Farmer

:::tip Updated from a previous version and now having issues?

Occasionally after updating to a new version of the Pulsar you will need to wipe your node and farmer, generally this should not be required but can be attempted if your farmer is having issues after having had worked fine previously.

:::
### Local Development

To simply restart the node, go to the terminal where you started the `farm` command, and press `Ctrl + C` you should see a shutdown message appear and the application will attempt a simple shutdown, if you dont see the message press `Ctrl + C` again to force shutdown. You can then simply start the farmer again with the `farm` command you used prior.
---

Use the same file name as the previous init and farm steps, then add the wipe command to free the previous storage that was being used. Generally, only do this if you have severe errors and are prompted by a staff member.
To run Pulsar in a local development mode, modify your `settings.toml` and ensure your `chain` points to `dev`:

```shell-session
./pulsar-file-name wipe
```toml
# settings.toml
[node]
chain = 'dev'
# ... redacted ...
```

After wiping, follow the `init` and `farm` steps above to start farming again!

### View your Logs

A good place to start if you are facing trouble is by viewing your logs and seeing if there are any errors or insights that might be available. You can find the location for your logs below

<Tabs groupId="OS">
<TabItem value="windows" label="🖼️ Windows" default>

Your Logs will be found in `%USERPROFILE%/AppData/Local/pulsar/logs`

</TabItem>

<TabItem value="macos" label="🍎macOS">

Your Logs will be found in `$HOME/Library/Logs/pulsar/`

</TabItem>

<TabItem value="linux" label="🐧Ubuntu">

Your Logs will be found in `$HOME/.local/share/pulsar/logs`

</TabItem>
</Tabs>

### Enable Rust Backtrace

When running the Subspace Network Farmer & Node, sometimes you may encounter an error message that includes a line similar to the following:
Expand Down

0 comments on commit e7f7e67

Please sign in to comment.