Docs

Docs

Getting Started

Initial setup instructions for installing Control Center on a Kubernetes cluster using Helm.

Control Center provides a streamlined way to manage Vaadin applications running on Kubernetes. This guide describes the required setup and explains how to deploy Control Center using Helm.

Prerequisites

Before installing Control Center, ensure the following requirements are met:

Kubernetes Cluster

A Kubernetes cluster must be available and reachable from the local development environment. This may be:

Note

This guide assumes deployment to a cloud-based Kubernetes environment. For local environments, refer to the Local Environment Setup documentation.

DNS Hostname

A DNS hostname must be available and resolvable to the cluster’s ingress or load balancer to access the Control Center UI.

Examples:

  • control.example.com → points to the cluster’s public IP address or load balancer.

  • control.local.gd → for local clusters; any *.local.gd domain resolves to 127.0.0.1.

Control Center can also be configured to automatically create DNS records for supported providers (for example, Google Cloud DNS), if appropriate credentials are provided. See Automatic DNS and Certificate Management for more details.

Helm

Helm must be installed and configured to communicate with the Kubernetes cluster.

Installation and usage instructions are available at Installing Helm.

Installation

Control Center is installed via a Helm chart. The following command installs the latest version, enables automatic TLS certificate management via Let’s Encrypt, and registers an initial user.

Source code
Terminal
helm install control-center oci://docker.io/vaadin/control-center \
  --namespace vaadin --create-namespace \
  --set app.host=control.example.com \
  --set user.email=me@example.com

This command includes the following parameters:

  • control-center: the Helm release name (customizable).

  • oci://docker.io/vaadin/control-center: the location of the Control Center Helm chart.

  • --namespace vaadin: installs the chart in the vaadin namespace, recommended to separate Control Center and its components from other workloads.

  • --create-namespace: creates the namespace if it doesn’t already exist.

  • --set app.host=…​: sets the hostname for accessing Control Center.

  • --set user.email=…​: sets the email address for the initial administrative user.

Tip

For a full list of available configuration values when installing Control Center, refer to the chart README on GitHub.

DNS and Certificates

Control Center uses HTTPS by default. Let’s Encrypt integration is enabled automatically and issues certificates for the hostname provided in app.host. This requires that the DNS record is already pointing to the cluster load balancer external IP address or that configuration for automatic DNS record creation is provided. Once the installation is complete, the load balancer external IP address can be found with this command:

Source code
Terminal
kubectl get svc -n vaadin control-center-ingress-nginx-controller

To use self-signed certificates instead (recommended for local clusters), the following override disables Let’s Encrypt and configures Control Center to use a built-in issuer:

Source code
Terminal
--set issuer.acme.enabled=false

After installation, the self-signed certificate authority used by Control Center can be extracted with:

Source code
Terminal
kubectl get secret control-center-ca -n vaadin -o go-template="{{ index .data "tls.crt" | base64decode }}" > control-center-ca.crt

To trust this certificate authority locally, use the appropriate method for the operating system:

Source code
Terminal
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain control-center-ca.crt
Terminal
Terminal
Terminal
PowerShell
PowerShell

Using an Existing TLS Certificate

Control Center can also be configured to use a pre-existing certificate—for example, a wildcard certificate managed externally. To use a custom certificate, create a Kubernetes Secret of type tls containing the certificate and private key:

Source code
Terminal
kubectl create secret tls my-custom-cert -n vaadin --cert=fullchain.pem --key=privkey.pem

The --cert and --key flags reference the public certificate and private key files, respectively. For more details on this command, refer to the official documentation: Using TLS Secrets.

To instruct Control Center to use this certificate instead of generating one, set the app.tlsSecret value during installation:

Source code
Terminal
--set app.tlsSecret=my-custom-cert
Important

When using a custom certificate, Control Center does not manage its renewal or rotation. Certificate validity and lifecycle management remain the responsibility of the administrator.

Persistent Storage and Database Configuration

Control Center provisions a Postgres cluster to host application databases and perform scheduled backups. It is critical to ensure that persistent data is stored on reliable and secure volumes, and that the cluster supports snapshot-based backups.

By default, Kubernetes uses the cluster’s default StorageClass and VolumeSnapshotClass to manage data persistence and backups. However, these defaults may not be optimized for durability, snapshot support, or security. It is strongly recommended to explicitly configure these values using the following Helm settings:

  • --set postgres.storageClass=…​

  • --set postgres.volumeSnapshotClass=…​

For details on how storage and backups are managed, and how to choose appropriate settings for your environment, refer to Database and Backups.

Note

To install Control Center by restoring a previous database backup, see the instructions in Restoring from a Backup.

Accessing Control Center

After installation completes, Control Center is available at:

Source code
https://control.example.com

The initial login requires a temporary password. This can be retrieved with:

Source code
Terminal
kubectl get secret control-center-initial-user -n vaadin -o go-template="{{ .data.password | base64decode | println }}"

Log in using the configured email address and the retrieved password. A password reset and profile setup are required on the first login.

Dashboard Overview

Once authenticated, the Control Center dashboard becomes available. At first launch, no applications are registered. The dashboard provides insights into application deployments, status, and health, and offers management tools for deploying and monitoring Vaadin applications.

To proceed with deploying Vaadin applications into the cluster, continue to the Application Deployment documentation.