Skip to content

Deployment Overview of Chainstack on Server

Prerequisites and Basic Requirements

To successfully deploy the Chainstack Control Panel, the server must meet the following operating system, hardware, and network requirements:

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

  • Privileges: Root access or a user with sudo privileges is required.

  • Architecture: 64-bit AMD64 (x86_64) or ARM64 (aarch64). 32-bit architectures are not supported.

  • Network: Access to the internet is required to download binaries, container images, and certificates.

  • Ports: The application listens on port 80 for HTTP and port 443 for HTTPS (via Traefik). Port 6443 is used internally by the Kubernetes API.

  • Swap Space: A swap file of 24G is automatically configured to ensure sufficient memory for blockchain nodes.

FQDN of the Final Panel

The Chainstack Control Panel is accessible via the hostkey.in domain. The fully qualified domain name follows the format:

chainstack<Server ID>.hostkey.in

The panel is served over HTTPS using a custom domain or the default temporary domain. The primary URL is configured as https://{{ final_domain }}. If a temporary domain is assigned during deployment, it is also accessible via HTTPS.

File and Directory Structure

The deployment places core binaries, configurations, and data in specific directories. The following structure represents the final state of the installation:

  • Installation Directory: /opt/chainstack

    • Contains the cpctl binary used for managing the Chainstack installation.

  • 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 panel URLs (mode 0600).

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

    • Contains kernel parameter tuning for blockchain nodes.

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

    • HelmChartConfig for Let's Encrypt certificate management.

  • Swap File: /swapfile

    • System swap file allocated for memory management.

Application Installation Process

The Chainstack Control Panel is installed using the cpctl installer, which deploys the application into a Kubernetes cluster running k3s.

  1. Container Runtime: The server uses k3s, a lightweight Kubernetes distribution.

  2. Version: The deployment targets version v1.0.0 of Chainstack.

  3. Namespace: All components are installed within the control-panel namespace.

  4. Storage Class: The deployment utilizes the local-path storage class for persistent volumes.

  5. Installation Command: The cpctl binary is executed to install the Control Plane with the following parameters: 

    /opt/chainstack/cpctl install -v v1.0.0 -s local-path -y

  6. Dependencies: The installation process installs the following tools:

    • kubectl: For Kubernetes interaction.

    • helm: For package management and deploying charts.

    • yq: For YAML processing.

    • Python client libraries (kubernetes, openshift, PyYAML) for ingress configuration.

Access Rights and Security

The deployment implements specific security measures to control access and manage resources:

  • Kyverno Policy: A ClusterPolicy named chainstack-node-resources is applied to enforce resource limits on blockchain nodes.

    • Applies to Pods in the control-panel namespace with label app.kubernetes.io/component: node.

    • CPU Limits: Set to 2 cores.

    • Memory Limits: Set to 8Gi.

  • Credentials:

    • The bootstrap password for the admin user is stored in /root/chainstack_admin_credentials.txt.

    • The file is owned by root with permissions 0600.

  • User Access: The default administrator username is admin.

  • Firewall: The k3s installation and Traefik ingress expose standard web ports (80, 443) externally. Internal communication occurs over port 6443.

Databases

The Chainstack Control Panel utilizes internal database services managed within the Kubernetes cluster.

  • Connection Method: Services connect to the database via internal Kubernetes DNS resolution within the control-panel namespace.

  • Storage Location: Data is stored on the node using the local-path storage class.

  • Configuration: Database settings are managed by the Helm chart and Kubernetes resources defined in the control-panel namespace. Specific connection strings are injected via environment variables or ConfigMaps within the cluster.

Docker Containers and Their Deployment

The application is deployed using Kubernetes resources, not standalone Docker containers. The core components include:

  • API Backend: cp-cp-deployments-api service, exposed on port 8080.

  • User Interface: cp-cp-ui service, exposed on port 80.

  • Ingress Controller: Traefik is used as the ingress controller to route traffic to the UI and API backends.

  • Node Resources: Blockchain nodes deployed by the user via the control panel are subject to the Kyverno policy resource constraints (2 CPU, 8Gi RAM).

  • Management: Deployments are managed via kubectl and the cpctl installer. The installer waits for all deployments to reach the Available condition before completing.

Proxy Servers

Traefik is configured as the reverse proxy and ingress controller for the Chainstack Control Panel.

  • SSL/TLS: Let's Encrypt is used to automatically generate and renew SSL certificates.

    • Resolver: le

    • Email: [email protected]

    • Storage: /data/acme.json within the Traefik deployment.

    • Challenge Type: TLS-ALPN (configured via --certificatesresolvers.le.acme.tlschallenge=true).

  • Routing:

    • Root Path (/): Routes to the cp-cp-ui service (port 80).

    • API Path (/api): Routes to the cp-cp-deployments-api service (port 8080). A middleware named chainstack-api-strip strips the /api prefix before forwarding to the backend.

  • Domains:

    • Ingress rules are created for the final domain (chainstack<Server ID>.hostkey.in).

    • If a temporary domain is provided, an additional ingress rule is created for that host.

Permission Settings

File and directory permissions are set to ensure security and proper functionality of the installed components:

  • Install Directory (/opt/chainstack): Mode 0755, Owner root:root.

  • cpctl Binary: Mode 0755 (executable).

  • Sysctl Config (/etc/sysctl.d/99-chainstack.conf): Mode 0644, Owner root:root.

  • Swap File (/swapfile): Mode 0600, Owner root:root.

  • Kubeconfig (/root/.kube/config): Mode 0600.

  • Credentials File (/root/chainstack_admin_credentials.txt): Mode 0600, Owner root:root.

  • Traefik Config Manifest: Mode 0644.

Location of Configuration Files and Data

All configuration files and runtime data are located in the following paths:

  • Chainstack Config: Managed within Kubernetes ConfigMaps in the control-panel namespace.

  • UI Configuration: The cp-cp-ui-config ConfigMap contains the config.json data, setting apiBaseUrl to /api.

  • Node Policy: The Kyverno policy file chainstack-node-policy.yaml is applied to the cluster to manage node resources.

  • Kernel Tuning: /etc/sysctl.d/99-chainstack.conf defines kernel parameters for blockchain node performance.

  • Certificates: Managed by Traefik in /data/acme.json (inside the Traefik pod volume).

Available Ports for Connection

The following ports are open and utilized by the deployment:

  • Port 80 (HTTP): Used for initial Let's Encrypt challenge and redirection to HTTPS.

  • Port 443 (HTTPS): The primary port for accessing the Chainstack Control Panel UI and API.

  • Port 6443: Internal Kubernetes API server port.

  • Port 8080: Internal API backend service port (accessed via Traefik proxy).

  • Port 80: Internal UI service port (accessed via Traefik proxy).

Starting, Stopping, and Updating

The Chainstack application and underlying infrastructure are managed using standard Kubernetes commands and service management tools.

  • Start/Restart: The k3s service manages the lifecycle of the Kubernetes cluster.

    • Command to start k3s: systemctl start k3s

    • Command to enable k3s on boot: systemctl enable k3s

  • Service Management:

    • The cpctl binary in /opt/chainstack/cpctl is used for installation and version management.

    • To verify the version of the installed cpctl binary: 

      /opt/chainstack/cpctl version

  • Updating Deployments:

    • Updates to the Chainstack Control Panel can be triggered by modifying the Helm release or restarting deployments via kubectl.

    • Example to restart the UI deployment: 

      kubectl rollout restart deployment cp-cp-ui -n control-panel

  • Checking Status:

    • Check if the Kubernetes node is ready: 

      kubectl get nodes

    • Check the status of all deployments in the control-panel namespace: 

      kubectl get deployments -n control-panel

  • Kernel Parameters: To apply new sysctl settings immediately: 

    sysctl --system

question_mark
Is there anything I can help you with?
question_mark
AI Assistant ×