> For the complete documentation index, see [llms.txt](https://canopy-network.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://canopy-network.gitbook.io/docs/secure-canopy/node-runner/quickstart.md).

# Quickstart

Your journey as a node runner starts here. For recommendations for system setup, please visit Setup & Recommendations.

{% hint style="danger" %}
**Disclaimer**: Canopy is alpha-stage software. While documentation and guides are provided to assist users, they are offered without warranties, guarantees, or assurances of reliability. Users are solely responsible for any issues that may arise, including but not limited to the loss of funds. Please proceed with caution.
{% endhint %}

{% hint style="info" %}
This guide assumes an x86 server running Ubuntu 26.06. Canopy also runs on ARM servers and other distributions. You may need to adapt the commands for your system.
{% endhint %}

### 0. Prerequisites

### Install necessary packages

<details>

<summary>Install Docker + Docker Compose</summary>

```bash
sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release

# Add Docker’s official GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Add Docker repo
echo \
  "deb [arch=$(dpkg --print-architecture) \
  signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine + CLI + Compose plugin
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

</details>

<details>

<summary>Make</summary>

`sudo apt install -y make`

</details>

<details>

<summary>Git</summary>

`sudo apt install -y git`

</details>

### Configure your DNS

{% hint style="info" %}
A public domain is required only for an active validator. If you are running a full node without public access, skip this section and the remaining DNS steps thorough the guide.
{% endhint %}

Your validator needs a domain that points to your server's public IP address.

Create these two `A` records in your DNS provider:

```
<YOUR_DOMAIN>     A     <SERVER_IP>
*.<YOUR_DOMAIN>   A     <SERVER_IP>
```

The first record points your root domain to the server. The wildcard record points every subdomain to the same server. Some DNS providers show the root domain as `@`.

Domain propagation can take some time. Check it with the following command:

```bash
nslookup YOUR_DOMAIN SERVER IP
```

{% hint style="info" %}
Ensure you've read and satisfied [Setup & Recommendations](/docs/secure-canopy/node-runner/setup-and-recommendations.md) before following the guide!
{% endhint %}

### 1. Clone the canopy node repo

```bash
git clone https://github.com/canopy-network/node.git
cd node
```

The [Canopy node repository](https://github.com/canopy-network/node) is the official source for setting up and operating validator infrastructure.

It contains the configuration, scripts, and monitoring tools required to participate in the Canopy network.

{% hint style="success" %}
Checkout this and extend this repository for more configuration options.
{% endhint %}

#### Migrate an existing node (optional)

If you are migrating a validator from the deprecated [deployments](https://github.com/canopy-network/deployments) repository, copy `validator_key.json` and `keystore.json` into the new node configuration.

```bash
cp /deployments/canopy_data/node1/validator_key.json /node/config/
cp /deployments/canopy_data/node1/keystore.json /node/config/
```

Otherwise, if you're migrating from another [node](https://github.com/canopy-network/node) repository. Copy the files from the same config path

```bash
cp /old_node/config/validator_key.json /node/config/
cp /old_node/config//keystore.json /node/config/
```

you can also copy the `.env` from the node repository to be migrated to keep the same configuration

```bash
cp /old_node/.env /node/config/.env
```

After copying these files, skip step 2. Continue with step 3 to verify the environment variables match the copied keys.

### 2. Generate a new private key

Run `make gen-key`, then enter a password and key name when prompted. The validator key is saved to `/node/config/validator_key.json` and the encrypted wallet key is saved to `/node/config/keystore.json`.

{% hint style="danger" %}
Copy and save the validator key from `/node/config/keystore.json` in a secure place, if somebody has access to that private key they will be able to own the validator!
{% endhint %}

### 3. Configure environment variables

Copy the provided `.env.example` file into a new `.env` file.

```bash
cp .env.example .env
```

Set the following `.env` fields to their required values:

```bash
# Open the file in Vim or another text editor
vim .env
```

* **DOMAIN:** Your validator's public domain. Configure it as a wildcard domain to serve each service. For example, use `example.com` or `canopy.example.com`. Each value generates these endpoints:
  * **`example.com`**
    * `example.com`: validator connection domain, used when staking
    * `wallet.example.com` : Wallet URL
    * `explorer.example.com` : Explorer URL
  * **`canopy.example.com`**
    * `canopy.example.com` : validator connection domain, used when staking
    * `wallet.canopy.example.com` : Wallet URL
    * `explorer.canopy.example.com` : Explorer URL
* **AUTH\_USER:** The basic-auth username for Wallet, Explorer, and Loki on the monitoring stack.
* **AUTH\_PASSWORD:** The basic-auth password for Wallet, Explorer, and Loki on the monitoring stack. Generate it with `make hash-password`, then **copy the command output into this environment variable**.

{% hint style="warning" %}
Save this information! It'll be used later to access the wallet and explorer.
{% endhint %}

#### Configure Grafana

Continuing the `.env` from the previous step, modify the following fields:

* **GF\_ADMIN\_USER**: The Grafana admin user.
* **GF\_ADMIN\_PASSWORD:** The Grafana admin password.

#### Set up alerting (optional)

The repository comes with a predefined set of alerts managed in the `monitoring` folder. To receive infrastructure and canopy alerts, configure the Discord and PagerDuty notification channel by modifying the following `.env` fields:

* **ALERTS\_DISCORD\_WEBHOOK:** [Discord Webhook URL](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) to receive notifications on a discord channel.
* **ALERTS\_PAGERDUTY\_ROUTING\_KEY:** A [Pagerduty Routing key](https://www.pagerduty.com/) to receive alerts on Pagerduty.

### 4. Run Canopy

Starting Canopy automatically pulls a snapshot of the latest blockchain.

```bash
make snapshot-up
```

{% hint style="success" %}
Syncing from scratch is also an option: you just need to run `make up` to start the complete stack from the genesis.
{% endhint %}

{% hint style="warning" %}
Important:

* Subsequent calls to `snapshot-up` will reset the data directory back to the latest snapshot.
* Use `make up` for a standard start without downloading the snapshot.
  * (See `/node/Makefile` for additional details and commands.)
    {% endhint %}

{% hint style="info" %}
To verify peer to peer connectivity, run `nc -vz <domain> 9001` from the command line. A successful response confirms that the validator accepts connections.
{% endhint %}

### 5. Explore Setup

With Canopy running, it is recommended for you to familiarize yourself with the created endpoints:

* Grafana: <mark style="color:blue;"><https://monitoring.\\>\<YOUR\_DOMAIN></mark>
* Web wallet for CNPY: <mark style="color:blue;"><https://wallet.\\>\<YOUR\_DOMAIN></mark>
* Block Explorer for CNPY: <mark style="color:blue;"><https://explorer.\\>\<YOUR\_DOMAIN></mark>

### 6. Sync the blockchain

While the snapshot is pretty close to the top of the blockchain, some syncing will be required in most cases.

Syncing status may be observed in the `Monitoring` tab of your web wallet as well as logs and rpc.

<figure><img src="https://2343293880-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLrZDX2RTu3ClIHkvyP7T%2Fuploads%2FFFu0ME0jqOrzJkAMn1wJ%2Fimage.png?alt=media&amp;token=b53d5f46-5063-4068-8bb8-91908767e618" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
The node should be fully synced and stable before staking.
{% endhint %}

If there's any sign of corruption or 'stuck' node or if there's any doubt, contact the community in [Discord](https://discord.gg/mUpUJ8ggz).

### 7. Create an 'output' private key

Go to <mark style="color:blue;"><https://wallet.\\>\<YOUR\_DOMAIN>/key-management</mark>

<figure><img src="https://2343293880-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLrZDX2RTu3ClIHkvyP7T%2Fuploads%2FxEdDHyPtyjpV6glsSsW3%2Fimage.png?alt=media&amp;token=ab431894-01cb-4b02-9bb2-20c9d982a1a6" alt=""><figcaption></figcaption></figure>

Press "Create New Key" and fill out the form:

{% hint style="info" %}
**Wallet name**: name to identify the new key

**Password**: used to encrypt the new key
{% endhint %}

**This new key will later receive your validator rewards**. It is recommended to download the `keyfile.json` and backup using the "Download Full Keystore" button.

### 8. Get CNPY

{% hint style="warning" %}
Canopy Betanet is permissioned. Please fill out [this application](https://forms.fillout.com/t/o8nxPZDTipus) for consideration.
{% endhint %}

### 9. Stake CNPY

At <mark style="color:blue;"><https://wallet.\\>\<YOUR\_DOMAIN>/staking</mark>: click the **+ Add Stake** button to initiate a **STAKE** transaction.

On **Step 1. Addresses** fill out the following:

* **Staking (Operator) Address:**
  * The address created on step 2.
  * Important: ⚠️ use the key from step 2 not step 8. ⚠️
  * This account should be the 'funded' account from step 2.
  * This is the operator address, where subsequent validator transactions like (`edit-stake` and `unstake`) should be sent from.
* **Reward Address**: Is the address where the staking rewards would go to, can be the same as the **Staking (Operator) Address** but is recommended to be different.

  <figure><img src="https://2343293880-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLrZDX2RTu3ClIHkvyP7T%2Fuploads%2FAVYUY6jmCiM4UQPN9weZ%2Fimage.png?alt=media&amp;token=8cd5e796-47ed-4fbd-a3f2-299200b4b9e3" alt=""><figcaption></figcaption></figure>

On **Step 2. Amount** fill out the following:

* **Amount:** Amount of CNPY to stake, the higher the amount the more likely the validator will be chosen to build the block.

<figure><img src="https://2343293880-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLrZDX2RTu3ClIHkvyP7T%2Fuploads%2FN9ZGdzPheK6g0c8r93VU%2Fimage.png?alt=media&amp;token=b7afa24f-429a-4b5d-955a-76385d39c762" alt=""><figcaption></figcaption></figure>

On **Step 3. Preferences** fill out the following:

* **Stake Type:** Choose **Validation.** Delegates are not active validators so is not applicable for this guide.
* **AutoCompound**: Preferably select this to auto stake the block rewards, otherwise you may leave unselected to withdraw the block rewards automatically (comes with a penalty).

<figure><img src="https://2343293880-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLrZDX2RTu3ClIHkvyP7T%2Fuploads%2Fg5fgR46aIBAV1sxVVkmM%2Fimage.png?alt=media&amp;token=d4619e17-a6e7-48cf-aba5-cd9439bd8034" alt=""><figcaption></figcaption></figure>

On **Step 4. Committees** fill out the following:

* **Committees:**
  * Chain IDs where stake should be allocated, type `1`.
* Validator Address: `tcp://<DOMAIN>`
  * Validator's TCP address (the same `<DOMAIN>` as defined in [step 3](#id-3.-configure-environment-variables)).

<figure><img src="https://2343293880-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLrZDX2RTu3ClIHkvyP7T%2Fuploads%2FhdWReaXTV2MqGGQ4Nvps%2Fimage.png?alt=media&amp;token=493684e2-d910-46f9-956a-4321a7261e40" alt=""><figcaption></figcaption></figure>

The last step is to review the information, once reviewed, click on **Stake.** It will prompt for the Operator addreess's password in order to submit the transaction.

<figure><img src="https://2343293880-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLrZDX2RTu3ClIHkvyP7T%2Fuploads%2FJGcMKM4YW3NLgAgdgURc%2Fimage.png?alt=media&amp;token=13791cc7-054e-4719-817a-4436c4959865" alt=""><figcaption></figcaption></figure>

If successful, after the block is processed, you'll see the node validator in the `Staking` tab like the example:

<figure><img src="https://2343293880-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLrZDX2RTu3ClIHkvyP7T%2Fuploads%2FMw8IJTx7WryJk7Icz6AC%2Fimage.png?alt=media&amp;token=c570e4b7-dd98-4722-8890-f4aaa9dc24da" alt=""><figcaption></figcaption></figure>

### 10. Watch for 10 minutes

* If `Status` remains `Staked` then it's a good sign that your Validator is online and healthy.

{% hint style="info" %}
See [Manage](/docs/secure-canopy/node-runner/manage.md) for monitoring and management details.
{% endhint %}