Deployment Overview of Chainstack on Server¶

Prerequisites and Basic Requirements¶

The following requirements must be met on the target server before deploying the Chainstack Control Panel:

• Operating System: Ubuntu (Linux) with apt package manager.

• Privileges: Root access or sudo privileges are required for installation and configuration.

• Domain: A valid domain name is required for the final panel URL. The system uses the hostkey.in zone with a specific prefix.

• Ports:

• Port 80 and 443 for HTTP/HTTPS traffic.

• Port 6443 for the Kubernetes API.

• Swap Space: A swap file of 24G is configured at /swapfile.

• System Tools: The installation process requires curl, wget, git, jq, ca-certificates, and openssl.

FQDN of the Final Panel¶

The fully qualified domain name (FQDN) for the Chainstack Control Panel follows the format:

chainstack<Server ID>.hostkey.in

The application is accessible via HTTPS at the URL defined by the variable panel_external_url, which resolves to https://chainstack<Server ID>.hostkey.in.

File and Directory Structure¶

The deployment utilizes the following directory structure for binaries, configurations, and data:

• Installation Directory: /opt/chainstack

• Contains the cpctl installer script.

• Kubernetes Configuration: /etc/rancher/k3s/k3s.yaml

• The primary kubeconfig file for the k3s cluster.

• Root Kubeconfig: /root/.kube/config

• A copy of the kubeconfig for root user access.

• Credentials File: /root/chainstack_admin_credentials.txt

• Stores the bootstrap admin password and access URLs.

• Sysctl Configuration: /etc/sysctl.d/99-chainstack.conf

• Contains kernel parameter tuning for blockchain nodes.

• Traefik Configuration: /var/lib/rancher/k3s/server/manifests/traefik-config.yaml

• Helm chart configuration for Traefik ingress and Let's Encrypt.

• Swap File: /swapfile

• The virtual memory swap file.

Application Installation Process¶

The Chainstack Control Panel is deployed using the cpctl installer within a k3s Kubernetes environment. The process involves the following steps:

1. Install Dependencies: Base packages including curl, wget, git, jq, ca-certificates, and openssl are installed.

2. Install Kubernetes Tools:

   • kubectl is installed to interact with the cluster.

   • Helm is installed for package management.

   • yq is installed for YAML processing.

3. Deploy k3s: The k3s lightweight Kubernetes distribution is installed with the argument --write-kubeconfig-mode 644.

4. Install cpctl: The cpctl binary is downloaded and installed to /opt/chainstack.

5. Deploy Control Plane: The Chainstack Control Plane is installed using the cpctl command with the following parameters:

   • Version: v1.0.0

   • Storage Class: local-path

   • Namespace: control-panel

   • Release Name: cp

6. Install Kyverno: The Kyverno policy engine is installed in the kyverno namespace to enforce resource limits on blockchain nodes.

Access Rights and Security¶

Security configurations are applied to ensure the integrity and safety of the deployment:

• Firewall: The system relies on the default firewall rules of the host. Ports 80, 443, and 6443 must be open.

• User Access:

• The root user has full access to the system and Kubernetes configurations.

• The cpctl binary is installed in /usr/local/bin or /opt/chainstack with executable permissions.

• Resource Limits: A Kyverno ClusterPolicy named chainstack-node-resources enforces CPU and memory limits on pods labeled with app.kubernetes.io/component: node in the control-panel namespace:

• CPU Request/Limit: 2 cores

• Memory Request/Limit: 8Gi

• Credentials: The bootstrap admin password is stored in /root/chainstack_admin_credentials.txt with permissions 0600 (readable only by root).

Databases¶

The Chainstack Control Panel utilizes persistent storage for its database and stateful components:

• Storage Class: local-path

• Namespace: control-panel

• Connection: The database is managed internally by the Helm chart and Kubernetes PersistentVolumeClaims. No external database connection string is required for the initial deployment.

Docker Containers and Their Deployment¶

The application is deployed using Kubernetes (k3s) rather than raw Docker containers. The deployment consists of the following components managed via Helm and Kubernetes manifests:

• Control Plane Components:

• cp-cp-deployments-api: Handles API requests.

• cp-cp-ui: Serves the user interface.

• Ingress Controller: Traefik is used as the ingress controller to route traffic.

• Policy Engine: Kyverno is deployed to manage cluster policies.

• Deployment Method:

• The cpctl tool manages the Helm release cp in the control-panel namespace.

• Kyverno is installed via the kyverno/kyverno Helm chart.

Proxy Servers¶

Traefik is configured as the reverse proxy and load balancer for the Chainstack Control Panel:

• Ingress Class: traefik

• TLS Configuration:

• Let's Encrypt is used for SSL certificate management.

• Email for Let's Encrypt: [email protected]

• Storage path for certificates: /data/acme.json

• Challenge method: tlschallenge

• Middleware:

• A middleware named chainstack-api-strip is created to strip the /api prefix for backend routing.

• Routing:

• Path /api routes to the cp-cp-deployments-api service on port 8080.

• Path / routes to the cp-cp-ui service on port 80.

• Configuration File: The Traefik configuration is applied via a HelmChartConfig manifest located at /var/lib/rancher/k3s/server/manifests/traefik-config.yaml.

Permission Settings¶

File and directory permissions are set as follows to ensure security and proper operation:

• Installation Directory: /opt/chainstack is set to 0755.

• cpctl Binary: Installed with executable permissions (0755).

• Kubeconfig Files:

• /etc/rancher/k3s/k3s.yaml: Mode 0644 (due to k3s install args).

• /root/.kube/config: Mode 0600.

• Credentials File: /root/chainstack_admin_credentials.txt is set to 0600.

• Swap File: /swapfile is set to 0600 with owner root:root.

• Sysctl Config: /etc/sysctl.d/99-chainstack.conf is set to 0644.

Location of Configuration Files and Data¶

Key configuration files and data locations are summarized below:

Available Ports for Connection¶

The following ports are utilized by the deployed services:

• Port 80: HTTP traffic (redirected to HTTPS).

• Port 443: HTTPS traffic for the Chainstack Control Panel UI and API.

• Port 6443: Kubernetes API server.

• Port 8080: Internal API service port (exposed via Ingress).

• Port 80: Internal UI service port (exposed via Ingress).

Starting, Stopping, and Updating¶

Service management is handled through Kubernetes and the k3s service:

• Start/Stop k3s:

• Start: systemctl start k3s

• Stop: systemctl stop k3s

• Enable on boot: systemctl enable k3s

• Update Chainstack Control Panel:

• The cpctl tool is used to manage the Helm release. To update, run the install command again with the desired version:

  /opt/chainstack/cpctl install -v <version> -s local-path -y
  

• Restart UI Deployment:

• The UI deployment can be restarted by patching the deployment annotation:

  kubectl patch deployment cp-cp-ui -n control-panel -p '{"spec":{"template":{"metadata":{"annotations":{"kubectl.kubernetes.io/restartedAt":"<timestamp>"}}}}}'
  

• Apply Sysctl Changes:

• To apply kernel parameter changes immediately:

  sysctl --system