# Rust node quick start (https://docs-i0yym09dy-ton-core-docs.vercel.app/llms/ecosystem/nodes/rust/quick-start/content.md)



Deploy a TON Rust node using the Helm chart.

For chart-specific values, configuration examples, and operator documentation such as networking, Vault, and monitoring, refer to the [chart README](https://github.com/RSquad/ton-rust-node/tree/master/helm/ton-rust-node).

## Image configuration [#image-configuration]

The Helm chart defines the container image through Helm values:

* `image.repository`
* `image.tag`

Avoid relying on a hard-coded tag in the documentation, because default values can change between chart releases.

To see the current defaults, refer to:

* [Chart values](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/values.yaml)
* [Chart `appVersion`](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/Chart.yaml)

## Node roles [#node-roles]

The chart deploys the same TON Rust node binary in two operational roles: validator and full node.

| Role      | Purpose                                                          | Ports to expose                                                                                                      |
| --------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Validator | Participates in consensus and validator elections.               | Keep `liteserver` and `jsonRpc` disabled; expose only required node and ops ports (`adnl`, and `control` if needed). |
| Full node | Syncs chain and serves external clients (APIs, explorers, bots). | Enable `liteserver`, `jsonRpc`, or both when external access is required.                                            |

* Run validators and full nodes as separate Helm releases so resources, security policy, and lifecycle stay isolated.
* If full chain history is needed, enable archival mode as described in [Archival node settings](/llms/ecosystem/nodes/rust/node-config/content.md).

## Quick start [#quick-start]

### Prerequisites [#prerequisites]

* Kubernetes cluster access configured for `helm`.
* [Helm 3 installed](https://helm.sh/docs/intro/install/).
* Access to the chart at `./helm/ton-rust-node` by cloning the [`ton-rust-node` repository](https://github.com/RSquad/ton-rust-node/tree/master/helm/ton-rust-node).
* A values file for the release, for example `values.yaml`.

Install and deploy TON Rust node with [Helm](https://helm.sh) using a minimal configuration, then optionally enable liteserver and JSON Remote Procedure Call (JSON-RPC) ports.

To deploy a validator, use this page for base deployment and keep the liteserver and JSON-RPC ports disabled. For validator election and operations workflow, use the validator guide [(`nodectl`)](https://github.com/RSquad/ton-rust-node/tree/master/helm/nodectl).

<div className="fd-steps">
  <div className="fd-step">
    ### Prepare a values file [#1-prepare-a-values-file]

    Not runnable

    ```yaml title="values.yaml"

    replicas: 2

    services:
      adnl:
        perReplica:
          - annotations:
              metallb.universe.tf/loadBalancerIPs: "1.2.3.4"
          - annotations:
              metallb.universe.tf/loadBalancerIPs: "5.6.7.8"

    nodeConfigs:
      node-0.json: |
        { "log_config_name": "/main/logs.config.yml", ... }
      node-1.json: |
        { "log_config_name": "/main/logs.config.yml", ... }
    ```

    The chart includes a mainnet [`globalConfig`](/llms/ecosystem/nodes/rust/global-config/content.md) and a default [`logsConfig`](/llms/ecosystem/nodes/rust/logs-config/content.md). This minimal setup requires only [`nodeConfigs`](/llms/ecosystem/nodes/rust/node-config/content.md).

    Other networking modes are described in the [Networking section](/llms/ecosystem/nodes/rust/node-config/content.md), including `NodePort`, `hostPort`, `hostNetwork`, and ingress controllers such as `ingress-nginx`.
  </div>

  <div className="fd-step">
    ### Install the release [#2-install-the-release]

    All `helm` commands below require [Helm to be installed](https://helm.sh/docs/intro/install/) and available in `PATH`.

    Use the local chart from [`ton-rust-node/helm/ton-rust-node`](https://github.com/RSquad/ton-rust-node/tree/e8bd0451b326099146a90a913beedaebd952fa56/helm/ton-rust-node):

    ```bash
    helm install <RELEASE_NAME> ./helm/ton-rust-node -f <VALUES_FILE>
    ```

    Or install from an Open Container Initiative registry:

    ```bash
    helm install <RELEASE_NAME> oci://ghcr.io/rsquad/ton-rust-node/helm/node -f <VALUES_FILE>
    ```
  </div>
</div>

## Verify deployment [#verify-deployment]

Check pod status for the release:

```bash
kubectl get pods -l app.kubernetes.io/name=node,app.kubernetes.io/instance=<RELEASE_NAME>
```

Check service status for the release:

```bash
kubectl get svc -l app.kubernetes.io/name=node,app.kubernetes.io/instance=<RELEASE_NAME>
```

## Enable liteserver and JSON-RPC ports [#enable-liteserver-and-json-rpc-ports]

Use this only for full node deployments. Do not expose these ports on validators.

Not runnable

```yaml
replicas: 2

ports:
  liteserver: 40000
  jsonRpc: 8081

services:
  adnl:
    perReplica:
      - annotations:
          metallb.universe.tf/loadBalancerIPs: "10.0.0.1"
      - annotations:
          metallb.universe.tf/loadBalancerIPs: "10.0.0.2"

nodeConfigs:
  node-0.json: |
    { "log_config_name": "/main/logs.config.yml", ... }
  node-1.json: |
    { "log_config_name": "/main/logs.config.yml", ... }
```

## Run multiple releases in the same namespace [#run-multiple-releases-in-the-same-namespace]

Use different release names:

```bash
helm install validator ./helm/ton-rust-node -f validator-values.yaml
helm install fullnode ./helm/ton-rust-node -f fullnode-values.yaml
```

This creates separate StatefulSets (`validator`, `fullnode`), services (`validator-0`, `fullnode-0`), and configs.

## Operational notes [#operational-notes]

### Helm hooks [#helm-hooks]

This chart does not rely on [Helm hooks](https://helm.sh/docs/topics/charts_hooks/) for bootstrap. Instead, an init container seeds `/main` from ConfigMaps and Secrets before the main container starts.

If pre- or post-deployment actions are required, such as backups before upgrades or data integrity checks, implement them outside the chart. This can be done in a CI/CD pipeline, dedicated Jobs, or Helm hooks in a wrapper chart.

Chart implementation references:

* [Init bootstrap script](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/files/init-script.sh)
* [StatefulSet init container](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/templates/statefulset.yaml)

### Ingress and TLS [#ingress-and-tls]

* The chart does not create Kubernetes `Ingress` resources.

  For UDP and TCP stream ports, including ADNL UDP, liteserver TCP, control TCP, a standard HTTP Ingress is not sufficient.

  If `ingress-nginx` is already used, [TCP and UDP ports can be exposed](https://kubernetes.github.io/ingress-nginx/user-guide/exposing-tcp-udp-services/) through its `tcp-services` and `udp-services` ConfigMaps, which enable stream proxying.

* TLS termination depends on the protocol used by the exposed port.

  * For HTTP-based ports such as some JSON-RPC setups, terminate TLS at an L7 proxy or an Ingress controller that supports HTTP routing.
  * For pure TCP stream proxying, terminate TLS at an external load balancer or TCP proxy, or use a TCP proxy that supports TLS passthrough or termination.
  * ADNL uses UDP and is typically exposed directly through `LoadBalancer`, `hostPort`, or `hostNetwork`. TLS termination does not apply to it in the same way as for HTTP.

* [Chart networking reference](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/docs/networking.md)

### PVC resizing and retention [#pvc-resizing-and-retention]

The chart defines `volumeClaimTemplates` in the StatefulSet for `main`, `db`, `keys`, and optionally `logs`.

PVC resizing (expansion) depends on the StorageClass configuration. If the StorageClass is `allowVolumeExpansion: true`, the PVC size can be increased by editing the PVC. Shrinking PVCs is not supported.

Related Kubernetes documentation:

* [PVC expansion overview](https://kubernetes.io/blog/2018/07/12/resizing-persistent-volumes-using-kubernetes/)
* If data must be preserved, consider using the PersistentVolume [reclaim policy](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy/) `Retain` instead of the default `Delete` for dynamically provisioned volumes.

Chart retention configuration:

* The chart supports `helm.sh/resource-policy: keep` for selected PVCs through `storage.<vol>.resourcePolicy`; defaults keep for `main` and `keys`.
* [Values chart](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/values.yaml)

### Safe upgrades, backups, and rolling restarts [#safe-upgrades-backups-and-rolling-restarts]

1. Use `helm upgrade` with an explicit image tag bump.
2. Treat the `db` and `keys` PVCs as critical state. Plan backups according to the storage backend.
3. Configuration changes:
   * Inline configuration changes trigger pod restarts through a checksum annotation.
   * External `existing*` ConfigMaps and Secrets are managed outside the chart. Changing them does not trigger an automatic rollout. Restart the pods or upgrade the release explicitly.

### Exposure mode examples [#exposure-mode-examples]

* Use one [exposure mode](/llms/ecosystem/nodes/rust/node-config/content.md) per deployment. Combining modes is possible but uncommon.
* [Chart implementation reference for per-port Services](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/templates/services.yaml)

### Vault integration using VAULT\_URL [#vault-integration-using-vault_url]

The chart supports an operator workflow where private keys are stored in an encrypted vault file, and the vault URL is passed through the `VAULT_URL` environment variable.

Recommended configuration (Secret-based):

```yaml
vault:
  secretName: ton-node-vault
  secretKey: VAULT_URL
```

The Secret should contain `VAULT_URL`. Example format: `file:///keys/vault.json&master_key=<64-hex-chars>`.

<Callout type="caution">
  In the RSquad chart workflow, Vault is configured through `VAULT_URL`. Do not rely on `secrets_vault_config` in `config.json` when using this approach.

  Keep the vault master key secure: it decrypts the vault file.
</Callout>

* [Chart Vault reference](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/docs/vault.md)
* Chart implementation references:
  * [`VAULT_URL` injection helper](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/templates/_helpers.tpl)
  * [Container env wiring](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/templates/statefulset.yaml)

## Useful commands [#useful-commands]

```bash
# Check pod status (replace "my-node" with the release name)
kubectl get pods -l app.kubernetes.io/name=node,app.kubernetes.io/instance=my-node

# Get external service IPs
kubectl get svc -l app.kubernetes.io/name=node,app.kubernetes.io/instance=my-node

# View logs
kubectl logs my-node-0 -c ton-node

# Exec into pod
kubectl exec -it my-node-0 -c ton-node -- /bin/sh
```