Skip to main content

Documentation Index

Fetch the complete documentation index at: https://chainstack-mintlify-flesh-empty-pages.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through a complete installation of Chainstack Self-Hosted on a dedicated server, from a fresh Ubuntu installation to a running Control Panel.

​
Overview

By the end of this guide, you will have:
  • A Kubernetes cluster running on your server
  • The Chainstack Self-Hosted Control Panel deployed and accessible
  • The ability to deploy blockchain nodes through the web interface

​
Prerequisites

Before starting, ensure you have:
  • A dedicated server or virtual machine meeting the system requirements
  • Root or sudo access to the server
  • A stable internet connection

​
End-to-end example

This example uses a dedicated server from Contabo running Ubuntu 22.04, but the steps apply to any compatible server.
1

Install required tools

Connect to your server via SSH and install the required dependencies. For detailed instructions, see Environment setup.
# Update package lists
apt update

# Install prerequisites
apt install curl gpg wget apt-transport-https --yes

# Install Helm
curl -fsSL https://packages.buildkite.com/helm-linux/helm-debian/gpgkey | gpg --dearmor | sudo tee /usr/share/keyrings/helm.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/helm.gpg] https://packages.buildkite.com/helm-linux/helm-debian/any/ any main" | sudo tee /etc/apt/sources.list.d/helm-stable-debian.list
apt update
apt install helm --yes

# Install yq (mikefarah version)
wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq
chmod +x /usr/local/bin/yq

# Verify installations
helm version
yq --version
2

Install Kubernetes (k3s)

k3s is a lightweight Kubernetes distribution that’s easy to install and suitable for single-server deployments. For detailed instructions, see Environment setup.
# Install k3s
curl -sfL https://get.k3s.io | sh -

# Configure kubectl to use k3s
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

# Make the configuration persistent
echo 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml' >> /etc/environment

# Verify the cluster is running
kubectl cluster-info
kubectl get nodes
You should see output indicating the cluster is running and your node is in Ready state.
3

Configure storage (optional but recommended)

If you have multiple disks available for blockchain node data, set up LVM and TopoLVM for dynamic storage provisioning. For detailed instructions, see Environment setup.
# Install LVM tools
apt install lvm2

# Find your disk devices (paths vary by provider)
lsblk

# Create physical volumes (replace with your actual disk devices)
pvcreate /dev/sdb /dev/sdc /dev/sdd

# Create volume group
vgcreate myvg1 /dev/sdb /dev/sdc /dev/sdd
Device paths vary by provider. The paths /dev/sdb, /dev/sdc, /dev/sdd are examples from Contabo. On DigitalOcean, volumes appear under /dev/disk/by-id/. On AWS, they may be /dev/nvme1n1, /dev/nvme2n1, etc. Always verify your actual device paths with lsblk before creating physical volumes.
# Install TopoLVM for Kubernetes storage provisioning
helm repo add topolvm https://topolvm.github.io/topolvm
helm repo update

# Create namespace and install cert-manager (required by TopoLVM)
kubectl create namespace topolvm-system
CERT_MANAGER_VERSION=v1.17.4
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/${CERT_MANAGER_VERSION}/cert-manager.crds.yaml

# Install TopoLVM
helm install --namespace=topolvm-system topolvm topolvm/topolvm --set cert-manager.enabled=true

# Check storage classes
kubectl get storageclass
If using TopoLVM, set it as the default storage class:
# Remove default from local-path
kubectl patch storageclass local-path -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"false"}}}'

# Set TopoLVM as default
kubectl patch storageclass topolvm-provisioner -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

# Verify
kubectl get storageclass
If you’re using the default k3s local-path storage class (single disk), you can skip this step.
4

Get the installer

Download the installer for your operating system.
5

Run the installation

Run the installer with your storage class and your server’s public IP. Replace <SERVER-IP> with the actual IP. This example uses topolvm-provisioner — the storage class set up in the previous step.
cpctl install -s topolvm-provisioner --backend-url http://<SERVER-IP>:8081
The --backend-url is the URL the browser will use to reach the deployments API. We expose the deployments API on port 8081 in the next steps. By default, the installer uses the latest version — to pin one, add -v vX.Y.Z (see Release notes for available versions).
The installer will:
  1. Check prerequisites (kubectl, helm, yq, openssl, cluster access)
  2. Generate secure passwords for all services
  3. Save the credentials to ~/.config/cp-suite/values/
  4. Prompt for the workload namespace where blockchain node pods will run (default: control-panel-deployments).
  5. Prompt to configure the monitoring stack — install fresh, reuse an existing VictoriaMetrics operator, or skip.
  6. Show a summary and ask you to confirm before deploying.
The installation typically takes 5–10 minutes. You’ll see output similar to:
→ Validating prerequisites...
✓ Checking kubectl installation
✓ Checking helm installation
✓ Checking helm version (v3+ required)
✓ Checking Kubernetes cluster connectivity
✓ All prerequisites validated successfully

==> Generating credentials for basic installation
→ Generating secure passwords...
→ Generating RSA keys for JWT authentication...
→ Saving credentials to config directory...
✓ Credentials saved: /root/.config/cp-suite/values/cp-control-panel-<timestamp>.yaml
✓ Storage class "topolvm-provisioner" validated

==> 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
6

Verify the installation

The installer shows a live progress table during deployment. Once complete, you should see:
✓ Installation completed successfully in 6m5s
✓ Installation completed successfully
You can also check the status at any time:
cpctl status
Look for the healthy status at the bottom of the output:
Overall Status: ✓ Healthy
Reason: All components ready
7

Expose the web interface and deployments API

Browser access requires exposing both the UI and the deployments API. The Ingress below puts the UI and Grafana on port 80; the deployments API is exposed separately on port 8081 to match the --backend-url you set during installation.Apply the Ingress for the UI and Grafana. The example uses Traefik, which k3s ships with by default:
kubectl apply -f - <<EOF
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cp-ui
  namespace: control-panel
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: web
spec:
  rules:
  - http:
      paths:
      - path: /grafana
        pathType: Prefix
        backend:
          service:
            name: cp-grafana
            port:
              number: 80
      - path: /
        pathType: Prefix
        backend:
          service:
            name: cp-cp-ui
            port:
              number: 80
EOF
Expose the deployments API on port 8081:
kubectl port-forward svc/cp-cp-deployments-api 8081:8080 -n control-panel --address 0.0.0.0 &
For testing without an ingress controller, use port forwarding for everything:
kubectl port-forward svc/cp-cp-ui 8080:80 -n control-panel --address 0.0.0.0 &
kubectl port-forward svc/cp-grafana 3000: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 &
The kubectl port-forward process must keep running for the deployments API to remain reachable. For production deployments, expose cp-cp-deployments-api via a LoadBalancer or NodePort instead — see Expose the UI and deployments API.
8

Access the Control Panel

Open your browser and navigate to:
  • Ingress: http://<SERVER-IP> — Control Panel, http://<SERVER-IP>/grafana — Grafana
  • Port forward: http://<SERVER-IP>:8080 — Control Panel, http://<SERVER-IP>:3000 — Grafana
You should see the Chainstack Self-Hosted login page.
9

Find your login credentials

The installer displays the username and a command to retrieve the password at the end of the installation:
==> Retrieving Bootstrap Admin Credentials

→ Username: admin
→ To retrieve the bootstrap password, run:

  yq '.cp-auth.env.CP_AUTH_BOOTSTRAP_PASSWORD' "/root/.config/cp-suite/values/cp-control-panel-<timestamp>.yaml"
Run the yq command from the output to get your password:
yq '.cp-auth.env.CP_AUTH_BOOTSTRAP_PASSWORD' /root/.config/cp-suite/values/cp-control-panel-*.yaml

​
Next steps

Congratulations! You now have Chainstack Self-Hosted running. Continue with:
  1. First login — First login and initial configuration
  2. Deploying nodes — Deploy your first blockchain node
  3. Troubleshooting — If you encounter any issues

​
Useful kubectl commands

Set the default namespace to avoid typing -n control-panel every time: 
kubectl config set-context --current --namespace=control-panel
Common commands for managing your installation: 
# View all pods
kubectl get pods

# View all services
kubectl get svc

# View persistent volume claims
kubectl get pvc

# View logs for a specific pod
kubectl logs <pod-name>

# Describe a deployment for troubleshooting
kubectl describe deployment cp-cp-deployments-api

# Restart a deployment
kubectl rollout restart deployment cp-cp-ui
Last modified on May 6, 2026