> 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="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 %}