# Setting Up a VSN (Storage)

Follow these simple steps to setup a Vola Smart Node for storage:

{% stepper %}
{% step %}

#### **Get $VOLA**

Use the [Vola Faucet](https://faucet.vola.network/) to load test $VOLA onto your [account](https://chromewebstore.google.com/detail/vola-wallet/bobefjjkdijgecmeclailfmnnoiagidp). You'll need enough to cover the registration fee and your staking requirement, which is based on the storage capacity you intend to commit.
{% endstep %}

{% step %}

#### Install Docker Engine

<details>

<summary>Uninstall old versions</summary>

Before you can install Docker Engine, you need to uninstall any conflicting packages.

Copy-paste the following command to uninstall all conflicting packages:

```
sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc | cut -f1)
```

You may be prompted for a Yes/No answer, press `y` & `enter`.

</details>

<details>

<summary>Install Docker Engine</summary>

Before you install Docker Engine for the first time on a new host machine, you need to set up the Docker `apt` repository. Afterward, you can install and update Docker from the repo.

Copy-paste the following commands to set it up:

```
# Add Docker's official GPG key:
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update
```

Continue to install the latest Docker packages:

```
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

You may be prompted for a Yes/No answer, press `y` & `enter`.

</details>

<details>

<summary>Start Docker &#x26; Verify Installation</summary>

Start the Docker Service:

```
sudo systemctl start docker
```

Verify that Docker is running:

```
sudo systemctl status docker
```

Verify that the installation is successful:

```
docker --version
docker compose version
```

</details>
{% endstep %}

{% step %}

#### Clone the Repository

```
git clone https://github.com/Nuvola-Digital/vola-smart-node-docker
cd vola-smart-node-docker
```

{% endstep %}

{% step %}

#### Run Setup

```
./setup.sh
```

The setup script is fully interactive. It walks you through every required value, writes them to `.env`, and then performs the one-time setup actions: creating the Docker network and volume, inserting the node key into the keystore, generating the node attestation, and optionally obtaining a TLS certificate.

Re-running the script is safe. Existing `.env` values are pre-filled as defaults.

#### What the script asks for:

**Node Key (`NODE_KEY_SURI`)**

Your node's secret URI - the identity it uses on-chain. The script can generate a fresh key for you automatically.

Prompt:

```
Node key (NODE_KEY_SURI) Generate a new node key now? [Y/n]: y
```

Output:

```
Network ID:        substrate
Secret seed:       0xaa2183443bc6e18c5e515ee8fea85b88e25958f210b9468da7348597e69cfe32
Public key (hex):  0x80c9b03b27af087bfb50620a8117587741bda83f3b937f22b7456c309bdeeb4d
Account ID:        0x80c9b03b27af087bfb50620a8117587741bda83f3b937f22b7456c309bdeeb4d
Public key (SS58): 5EyZuB7CmTT3h54CWM9xgGQKMzmBMdMhtrompf1a1c6DcJTy
SS58 Address:      5EyZuB7CmTT3h54CWM9xgGQKMzmBMdMhtrompf1a1c6DcJTy
```

{% hint style="warning" icon="cloud-check" %}
Store your keys securely. Your SURI and NODE\_KEY grant control over your node. Never share them and keep secure backups.
{% endhint %}

**Vola Chain RPC (`CHAIN_RPC`)**

Choose the RPC endpoint your node will connect to.

Prompt:

<pre><code>1) Public testnet-0 wss://rpc-testnet-0.volanetwork.io
2) Public testnet-1 wss://rpc-testnet-1.volanetwork.io
3) Local RPC node ws://vola-node:9944 (recommended, requires running vola-node)
4) Custom URL
<strong>Enter choice [1-4] [1]: 3
</strong></code></pre>

Output:

```
Local RPC selected — docker compose will also start the vola-node service.
CHAIN_RPC = ws://vola-node:9944
```

**Storage Volume Path (`STORAGE_VOLUME_PATH`)**

The host directory that backs the Docker volume used for node data (chain DB, keystore, TLS material, and file storage). Created automatically if it doesn't exist.

Prompt:

<pre><code><strong>Host path for storage volume [/home/vola-smart-node-docker/vsn-data]:
</strong></code></pre>

To select default storage path, press *Enter.*

**Storage amount (`VOLA_STORAGE`)**

The amount of storage in GiB this node commits to the network. The script reports available free space on the target filesystem before you confirm.

Prompt:

<pre><code>Minimum required: 500 GiB.
Free space on the filesystem holding /home/vola-smart-node-docker/vsn-data: 33300 GiB.
<strong>Storage amount in GiB [500]: 33300
</strong></code></pre>

Output:

```
VOLA_STORAGE = 33300 GiB
```

**TLS mode ( `USE_DOMAIN_PROVIDER_MANAGED_TLS_CERTIFICATE`)**

Select TLS mode to be used.

Prompt:

<pre><code>1) Provider-managed TLS  (e.g. Cloudflare proxied or Vola Domain Provider; node binds port 80)
0) Self-managed (local TLS via Let's Encrypt; node binds port 443)
<strong>Enter choice [0/1] [1]: 1
</strong></code></pre>

Output:

```
TLS mode = provider-managed
```

**Gateway domain (`GATEWAY_DOMAIN`)**

The public domain pointing to your node (e.g. `vsn.example.com`). Leave blank if you have selected Provider-managed TLS in previous step.

Prompt:

<pre><code>Optional for provider-managed TLS. Leave blank to set it later.
<strong>Public domain (press enter to skip):
</strong></code></pre>

Press *Enter* to skip.

**Operator wallet address (`OPERATOR_KEY_ADDRESS`)**

The Vola address of the operator wallet (from Vola Wallet) that will own this node via the Vola Dashboard (e.g. `5HWJriJJufkWeTFRbBit2gtAkoCGZ28H1uZadokSspzD1EAF`).

Prompt:

<pre><code><strong>Operator wallet address (SS58):
</strong></code></pre>

Input wallet address, and press *Enter.*

**Output:**

<pre><code>Writing .env
----------------------------------------
.env updated.
Creating Docker network vola-network...
Created Docker network vola-network.
Creating storage volume directory at /home/vola-smart-node-docker/vsn-data...
Creating Docker volume vola-smart-node-data backed by /home/vola-smart-node-docker/vsn-data...
Created Docker volume vola-smart-node-data -> /home/vola-smart-node-docker/vsn-data
Using Docker image: docker.io/nuvolalabs/vola-smart-node:latest
Docker image docker.io/nuvolalabs/vola-smart-node:latest is already available locally.
Inspecting node key...
Node key address: 5EyZuB7CmTT3h54CWM9xgGQKMzmBMdMhtrompf1a1c6DcJTy
Operator key address: 5HWJriJJufkWeTFRbBit2gtAkoCGZ28H1uZadokSspzD1EAF
Inserting node key into keystore at /data/keystore...
Running node setup (creating attestation)...
<strong>Setup completed successfully!
</strong></code></pre>

Example attestation output:

<pre><code>Attestation file:     /data/storage/.vsn-node-attestation
Node key:             0x0cebd69a18a262dc9008c316f7d22a19f0ed95d89ca24942fcd6ec67a84ee57d
Operator key:         0x0cebd69a18a262dc9008c316f7d22a19f0ed95d89ca24942fcd6ec67a84ee57d
Storage anchor:       0xef0bd7bbf49e907b399c2b3d444490b9c3029f06ac7360b137c1ed5c5bd03984
Vola storage:         33300 GB
CPU cores:            4
RAM:                  31829 MiB
Disk read:            500 MiB/s
Disk write:           549 MiB/s
Network download:     112 MiB/s
Network upload:       109 MiB/s
Attestation hash:     0x12a7b5789a6e9df15bdd6cf6ab9466ddffeb2d19b3ee1e08d2de57ac911b70a9
<strong>Encoded attestation:  0x01000000ef0bd7bbf49e907b399c2b3d444490b9c3029f06ac7360b137c1ed5c5bd039841482000000000000000cebd69a18a262dc9008c316f7d22a19f0ed95d89ca24942fcd6ec67a84ee57d000cebd69a18a262dc9008c316f7d22a19f0ed95d89ca24942fcd6ec67a84ee57df40125026d00700004557c000001261f43a50988ba13d8892583539ca1deccb2c9a339751e0a921ebbb7f8c8727bc8b9e32883fa6e5cea24f84164fefa86d35cbabf7557917fe8af2bf6e3514187
</strong>
✔ Node attestation created.
✔ Skipping local TLS setup because the domain provider manages TLS certificates.
✔ Setup complete. Run 'docker compose up -d' to start the node.
</code></pre>

{% hint style="success" icon="cloud-check" %}
Copy `Encoded Attestation` to Vola Dashboard to Activate Your Node

Ex: `0x01000000ef0bd7bbf49e907b399c2b3d444490b9c3029f06ac7360b137c1ed5c5bd039841482000000000000000cebd69a18a262dc9008c316f7d22a19f0ed95d89ca24942fcd6ec67a84ee57d000cebd69a18a262dc9008c316f7d22a19f0ed95d89ca24942fcd6ec67a84ee57df40125026d00700004557c000001261f43a50988ba13d8892583539ca1deccb2c9a339751e0a921ebbb7f8c8727bc8b9e32883fa6e5cea24f84164fefa86d35cbabf7557917fe8af2bf6e3514187`
{% endhint %}
{% endstep %}

{% step %}

#### Start Your Node

Run the below command to start your node in the background (detached), remove the `-d` from the command to run it in the foreground (not recommended)

```
docker compose up -d
```

Output:

```
✔ Container vola-node         Started
✔ Container vola-smart-node   Started
```

Use `docker logs -f <container id>` to check the logs.

Use `docker compose restart` to restart the node.

Use `docker ps` to check running containers. Look for the below output.

```
CONTAINER ID   IMAGE                               COMMAND          CREATED      STATUS        PORTS                                                                                                                    NAMES
403b753b2d6b   nuvolalabs/vola-smart-node:latest   "/entry.sh"      6 days ago   Up 13 hours   0.0.0.0:80->1331/tcp, [::]:80->1331/tcp                                                                                  vola-smart-node
2df3e08b7c48   nuvolalabs/vola-node:latest         "/run-node.sh"   6 days ago   Up 13 hours   0.0.0.0:9615->9615/tcp, [::]:9615->9615/tcp, 0.0.0.0:30333->30333/tcp, [::]:30333->30333/tcp, 127.0.0.1:9944->9944/tcp   vola-node
```

{% endstep %}

{% step %}

#### **Managing Your Node (Optional)**

Re-run `./setup.sh`. Existing `.env` values are pre-filled as defaults. Press enter through any prompt you don't want to change. The script uses `--force` when regenerating the attestation and will overwrite the existing one.

**Available scripts**

<table><thead><tr><th width="239.90625">Scripts</th><th width="439.19140625">What it does</th></tr></thead><tbody><tr><td><code>./setup.sh</code></td><td>Interactive full setup - env prompts, network, volume, attestation, TLS</td></tr><tr><td><code>./generate-wallet-key.sh</code></td><td>Generate a new wallet key / SURI standalone</td></tr><tr><td><code>./scripts/setup-tls.sh</code></td><td>Obtain or refresh a local TLS certificate independently</td></tr><tr><td><code>./scripts/register.sh</code></td><td>Register the node on-chain (prompts for operator key and gateway details)</td></tr><tr><td><code>./scripts/request-domain.sh</code></td><td>Request a managed domain from the Vola Domain Provider</td></tr><tr><td><code>./scripts/update-info.sh</code></td><td>Update the registered gateway domain or port on-chain</td></tr></tbody></table>

**Updating the node software**

```
# Pull the latest image
docker pull nuvolalabs/vola-smart-node:latest

# Restart with the updated image
docker compose down
docker compose up -d
```

During testnet, chain purges may occasionally be required due to protocol changes. If a purge occurs, you will need to re-register your node on-chain. Once the network transitions to mainnet, updates will be handled through runtime upgrades and re-registration will not be needed.

**Troubleshooting**

<table><thead><tr><th width="215.5390625">Problem</th><th width="468.2109375">What to check</th></tr></thead><tbody><tr><td>Registration or on-chain update fails</td><td>Verify the operator account has enough VOLA for fees and existential balance</td></tr><tr><td>Let's Encrypt HTTP challenge fails</td><td>Ensure port <code>80</code> is reachable from the internet, or complete the DNS fallback flow</td></tr><tr><td>Node can't reach the chain RPC</td><td>Check that the Docker network is configured correctly and the RPC endpoint is accessible from inside the container</td></tr><tr><td>Docker requires elevated privileges</td><td>Run commands with the appropriate user permissions for your host</td></tr></tbody></table>

{% endstep %}

{% step %}

### Register the Node On-Chain

Go to [**Vola Network - Nodes**](https://testnet.vola.network/nodes) and register your node using:

* Your **node key `Public key (SS58)`** (printed during [Step 4](#what-the-script-asks-for))
* The **encoded attestation** (printed at the end of setup)

**Save your Node ID.** You will receive it upon successful registration. You'll need it if you ever update your node's gateway domain or port on-chain.

{% endstep %}

{% step %}

### Stake Storage

Your node will only start receiving files after its committed storage has been staked.\
Go to [**Vola Network - Nodes**](https://testnet.vola.network/nodes) to manage staking.

**Staking notes:**

* You must stake at least **500 GiB** to activate the node.
* Any remaining committed storage above your own stake can be opened for delegation, allowing others to stake into your node.

{% endstep %}
{% endstepper %}

{% hint style="success" icon="cloud-check" %}
**If you follow all these steps correctly, your VSN setup and on-chain registration is complete.**&#x20;
{% endhint %}

#### Staking

Every Storage Node must stake $VOLA to participate in the network. The required stake is calculated based on the storage capacity you commit, the more storage you offer, the more you need to stake.

Your stake isn't spent; it's locked as collateral. Your stake is returned in full when you retire your node from the network, minus any applicable penalties.

{% content-ref url="/pages/1Z3WvSS7obhDHKQnv0JD" %}
[Node Staking](/docs/vola-node-economy/staking-and-delegation/node-staking.md)
{% endcontent-ref %}

#### Rewards

Storage Nodes earn from two streams:

1. storage fee revenue from users whose files they store, and,
2. staking rewards based on their committed stake relative to the network.

Both streams are weighted by your node's performance score.

Early node operators also benefit from a Revenue Multiplier, a time-decaying bonus applied on top of storage fee revenue during the network's early stages.

{% content-ref url="/pages/3Xr3L81JEkDpfquNCjaW" %}
[Node Rewards](/docs/vola-node-economy/staking-and-delegation/node-rewards.md)
{% endcontent-ref %}

#### Request Delegation

If you don’t have enough $VOLA to meet the full staking requirement, you can open your node to public delegators. This allows other $VOLA holders to contribute stake and share in the node’s rewards. You set the percentage of revenue you retain, and the rest is distributed proportionally among delegators.

{% content-ref url="/pages/SrIob2jhz2NibYMEluAH" %}
[Delegated Staking](/docs/vola-node-economy/staking-and-delegation/delegated-staking.md)
{% endcontent-ref %}

### What's Next?

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Node Staking Requirements</strong></td><td><em>Understand the staking formula and how your stake affects your position in the network.</em></td><td><a href="/pages/1Z3WvSS7obhDHKQnv0JD">/pages/1Z3WvSS7obhDHKQnv0JD</a></td></tr><tr><td><strong>Node Rewards</strong></td><td><em>How validator rewards are calculated and when they are distributed.</em></td><td><a href="/pages/3Xr3L81JEkDpfquNCjaW">/pages/3Xr3L81JEkDpfquNCjaW</a></td></tr><tr><td><strong>Delegated Staking</strong></td><td><em>Open your node to delegators or delegate your $VOLA to an existing node.</em></td><td><a href="/pages/SrIob2jhz2NibYMEluAH">/pages/SrIob2jhz2NibYMEluAH</a></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wp.vola.network/docs/vola-node-economy/vola-nodes-overview/vola-smart-nodes-storage/setting-up-vsn-storage-nodes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.