> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/docs/self-hosted/advanced-installation).

## Prerequisites

Before installation, make sure you have a running Kubernetes cluster with kubectl, Helm, yq, and openssl installed. See [Environment setup](/docs/self-hosted/environment-setup) for instructions and a verification checklist.

## Install

<Steps>
  <Step title="Run the installer">
    Find your storage class name:

    ```bash theme={"system"}
    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:

    ```bash theme={"system"}
    cpctl install -s STORAGE_CLASS_NAME
    ```

    For example:

    ```bash theme={"system"}
    cpctl install -s topolvm-provisioner
    ```

    <Note>
      By default, the installer uses the latest version. To pin a specific version, add `-v vX.Y.Z` — see [Release notes](/docs/self-hosted/release-notes) for available versions.
    </Note>

    To get the installer, see [Download Chainstack Self-Hosted](/docs/self-hosted/download-installer).
  </Step>

  <Step title="Confirm auto-generation">
    When prompted, confirm that you want to auto-generate passwords:

    ```text theme={"system"}
    No values file provided. Generate passwords automatically? [y/N]: y
    ```
  </Step>

  <Step title="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.

    ```text theme={"system"}
    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](#expose-the-ui-and-deployments-api). 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.

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

  <Step title="Specify the workload namespace">
    The installer will ask for the Kubernetes namespace where blockchain node pods will run:

    ```text theme={"system"}
    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.
  </Step>

  <Step title="Choose monitoring configuration">
    The installer will prompt you to configure the monitoring stack:

    ```text theme={"system"}
    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.
  </Step>

  <Step title="Confirm and deploy">
    The installer will show a summary and ask you to confirm:

    ```text theme={"system"}
    ==> 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).
  </Step>
</Steps>

### Credentials storage

Generated credentials are saved to:

```text theme={"system"}
~/.config/cp-suite/values/cp-control-panel-<timestamp>.yaml
```

<Warning>
  This file contains sensitive passwords and keys. Keep it secure and backed up.
</Warning>

## 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](/docs/self-hosted/monitoring) for access instructions and available dashboards.

### Verify deployment status

```bash theme={"system"}
cpctl status
```

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

```text theme={"system"}
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](#specify-the-url-for-the-backend) — by default, that's `http://<SERVER-IP>:8081`, which routes to the deployments API.

#### Option 1: LoadBalancer (recommended for production)

```bash theme={"system"}
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

```bash theme={"system"}
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):

```yaml theme={"system"}
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)

```bash theme={"system"}
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](/docs/self-hosted/first-login) — First login and configuration
2. [Deploying nodes](/docs/self-hosted/deploying-nodes) — Deploy your first blockchain node
3. [Advanced installation](/docs/self-hosted/advanced-installation) — Customize your deployment