Installation

Install Chainstack Self-Hosted using cpctl with auto-generated defaults for a streamlined deployment of your self-managed blockchain node infrastructure.

This guide walks through a standard installation with auto-generated passwords and default settings. For custom deployments — external databases, adjusted resource limits, or manual values — see Advanced installation.

Prerequisites

Before installation, make sure you have a running Kubernetes cluster with kubectl, Helm, yq, and openssl installed. See Environment setup for instructions and a verification checklist.

Install

1. Run the installer

   Find your storage class name:

   kubectl get storageclass
   

   Common storage classes:

   • local-path — default k3s storage class (single-disk setups)
   • topolvm-provisioner — TopoLVM (multi-disk setups)
   • Cloud providers use their own defaults (gp2/gp3 on AWS, standard on GCP, managed-premium on Azure)

   Run the installer with your storage class:

   cpctl install -s STORAGE_CLASS_NAME
   

   For example:

   cpctl install -s topolvm-provisioner
   

   By default, the installer uses the latest version. To pin a specific version, add -v vX.Y.Z — see Release notes for available versions.

   To get the installer, see Download Chainstack Self-Hosted.

2. Confirm auto-generation

   When prompted, confirm that you want to auto-generate passwords:

   No values file provided. Generate passwords automatically? [y/N]: y
   
3. Specify the URL for the backend

   The installer will ask for the backend API URL. This is the URL the Control Panel UI uses to reach the deployments API. The browser must be able to resolve and reach this URL — an in-cluster hostname will not work for browser access.

   Enter CP UI backend API URL [http://cp-cp-deployments-api]:
   

   • Single server, browser access (recommended) — enter http://<SERVER-IP>:8081. You will expose the deployments API on port 8081 in Post-installation. Use port 80 (or another free port) instead of 8081 if it suits your environment, but match it during exposure.
   • In-cluster only (rare) — press Enter to keep http://cp-cp-deployments-api. This is reachable only from inside the cluster, so the UI will fail to log in from a browser outside.

   You can skip this prompt by passing --backend-url http://<SERVER-IP>:8081 to cpctl install.

4. Specify the workload namespace

   The installer will ask for the Kubernetes namespace where blockchain node pods will run:

   Enter workload namespace for blockchain nodes [control-panel-deployments]:
   

   Press Enter to accept the default control-panel-deployments. Change it only if you need a custom namespace layout.

5. Choose monitoring configuration

   The installer will prompt you to configure the monitoring stack:

   Monitoring stack:
     [1] Install monitoring stack (clean cluster, no existing VictoriaMetrics)
     [2] Install monitoring using existing VictoriaMetrics operator
     [3] Skip monitoring
   
   Choice [1]:
   

   • Option 1 — installs the full monitoring stack (Grafana, VictoriaMetrics, exporters). Use this for a clean cluster.
   • Option 2 — reuses an existing VictoriaMetrics operator already deployed on the cluster.
   • Option 3 — skips monitoring entirely.
6. Confirm and deploy

   The installer will show a summary and ask you to confirm:

   ==> About to install Control Panel
     Version: v1.8.0
     Namespace: control-panel
     Workload Namespace: control-panel-deployments
     Release: cp
     Timeout: 15m0s
   
   Do you want to proceed? [y/N]: y
   

   Confirm with y. The installer will then deploy the full stack (PostgreSQL, Temporal, Keycloak, Control Panel services).

Credentials storage

Generated credentials are saved to:

~/.config/cp-suite/values/cp-control-panel-<timestamp>.yaml

This file contains sensitive passwords and keys. Keep it secure and backed up.

Post-installation

Monitoring stack

The Control Panel includes an optional integrated observability stack (Grafana, VictoriaMetrics, and the Chainstack blockchain-node-exporter). During installation, you are prompted to install it, reuse an existing VictoriaMetrics operator, or skip it. See Monitoring for access instructions and available dashboards.

Verify deployment status

cpctl status

Look for the healthy status at the bottom of the output:

Overall Status: ✓ Healthy
Reason: All components ready

Useful flags:

Flag	Description
-w, --watch	Watch status with continuous updates
--wide	Show full resource names without truncation
--no-pods	Hide pod details for a cleaner view
--unhealthy-only	Show only unhealthy or degraded components
-o json / -o yaml	Machine-readable output for automation
--log-file <path>	Write the status output to a file

Expose the UI and deployments API

For browser access to work, you need to expose two services to the network: the UI (cp-cp-ui) and the deployments API (cp-cp-deployments-api). The UI page is served by the first; the JavaScript in the page calls the URL you set in the backend URL step — by default, that’s http://<SERVER-IP>:8081, which routes to the deployments API.

Option 1: LoadBalancer (recommended for production)

kubectl expose service cp-cp-ui --type=LoadBalancer --name=cp-ui-external -n control-panel
kubectl expose service cp-cp-deployments-api --type=LoadBalancer --name=cp-deployments-api-external -n control-panel --port=8081 --target-port=8080

Option 2: NodePort

kubectl expose service cp-cp-ui --type=NodePort --name=cp-ui-nodeport -n control-panel
kubectl expose service cp-cp-deployments-api --type=NodePort --name=cp-deployments-api-nodeport -n control-panel --port=8081 --target-port=8080

Option 3: Ingress

Create an Ingress that exposes the UI on port 80. The deployments API is exposed separately on port 8081 via a LoadBalancer or port-forward (see Options 1 or 4):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cp-ui-ingress
  namespace: control-panel
spec:
  rules:
  - host: cp.yourdomain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: cp-cp-ui
            port:
              number: 80

Option 4: Port forward (testing only)

kubectl port-forward svc/cp-cp-ui 8080:80 -n control-panel --address 0.0.0.0 &
kubectl port-forward svc/cp-cp-deployments-api 8081:8080 -n control-panel --address 0.0.0.0 &

Next steps

1. First login — First login and configuration
2. Deploying nodes — Deploy your first blockchain node
3. Advanced installation — Customize your deployment