Quick start

Complete walkthrough from a fresh Ubuntu installation to a running Chainstack Self-Hosted Control Panel with your first blockchain node deployed.

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