Getting Started

The basics of how to use Control Center.

Prerequisites
Deploying Control Center
Accessing Control Center

Control Center simplifies the management of Vaadin applications on Kubernetes clusters. This page explains how to deploy Control Center and get it running smoothly.

Prerequisites

Before you begin, make sure you have a Kubernetes cluster running and available. It can be a cloud-based service like Google Kubernetes Engine (GKE), Amazon EKS, or Azure AKS. Alternatively, you can use a local cluster with tools like Docker Desktop, which has an embedded Kubernetes (see Kubernetes on Docker Desktop), or minikube. Deciding which to use depends on your project needs.

Important

If you’re using minikube, you’ll need to ensure that the minikube tunnel is running before deploying Control Center.

You’ll also need to install Helm. It’s a Kubernetes package manager that simplifies application deployment and management. Make sure it’s configured to interact with your cluster.

Deploying Control Center

To deploy Control Center to a Kubernetes cluster, the process depends on whether you’re using it in a development or production environment. The following sections explain how to deploy Control Center in each case.

Development Environment

Granting administrator privileges enables automatic installation of required dependencies. If you choose not to grant these privileges, though, you’ll need to install the required resources before installing Control Center. See the Installation of Dependencies section for details on how to do this.

For use in a development environment, you might install Control Center like so:

helm install control-center oci://docker.io/vaadin/control-center \
    -n control-center --create-namespace \
    --set serviceAccount.clusterAdmin=true \
    --set service.type=LoadBalancer --set service.port=8000 \
    --wait

This installs Control Center.
This creates a dedicated namespace to isolate Control Center from other applications.
Grants administrative privileges that allow Control Center to manage cluster resources.
Configures service settings for a load balancer on port 8000. Change the port if necessary for your environment.
This instructs Helm to wait until Control Center is fully deployed.

Production Environment

For use in a production environment, you’ll need to install manually the required dependencies. See the Installation of Dependencies section for details on how to do this.

Once you’ve installed the dependencies, you can install Control Center like this:

helm install control-center oci://docker.io/vaadin/control-center \
    -n control-center --create-namespace \
    -f values-ingress.yaml \
    --wait

This installs Control Center.
This creates a dedicated namespace to isolate Control Center from other applications.
Configures a custom ingress configuration (see below).
This instructs Helm to wait until Control Center is fully deployed.

This is an example of a custom ingress configuration:

ingress:
  enabled: true
  className: "nginx"
  hosts:
    - host: "control-center.example.com"
      paths:
        - path: "/"
          pathType: Prefix
  tls:
    - hosts:
        - "control-center.example.com"
      secretName: "control-center-tls"

This ingress configuration assumes that you have already a certificate in your production environment. To create the control-center-tls secret for the certificate you should run this command:

kubectl -n control-center create secret tls control-center-tls --cert=cert.pem --key=key.pem

If you don’t have a certificate, or you’re not deploying to a production environment, you can create one with a tool like mkcert, using the following:

mkcert control-center.example.com

This creates the cert.pem and key.pem files.

Accessing Control Center

Once deployed, you can access Control Center through the web browser. For a local cluster, navigate to http://localhost:8000. For a cloud cluster, use the external IP or domain assigned by your cloud provider.

You’ll see the Startup Configuration Wizard. It’ll help you to configure authentication and essential settings using OpenID Connect.

Retrieve Passkey

The wizard requires a passkey to proceed. Run the following command to retrieve it:

kubectl -n control-center get secret control-center-passkey -o go-template="{{ .data.passkey | base64decode | println }}"

Configure Keycloak Hostname

Keycloak is the identity provider used by Control Center. Therefore, you’ll need to configure the hostname for it. It needs a hostname that is accessible from within the Kubernetes cluster and from a web browser running outside the cluster.

The hostname allows your applications and users to authenticate securely via Keycloak. This is necessary for both secure authentication and browser accessibility. Applications in the cluster need to access Keycloak to authenticate users, securely. At the same time, since authentication often involves redirects to Keycloak’s login page, your browser must be able to reach Keycloak using a resolvable hostname.

Therefore, the hostname must resolve to an IP address reachable by both the cluster and external clients (e.g., the browser). Proper DNS configuration ensures secure and reliable communication.

Cloud Environments

For cloud deployments, first create a DNS record. Point it to your cluster’s public IP address provided by your cloud provider. For example, if your domain is mydomain.com, you might create keycloak.mydomain.com pointing to the cluster’s external IP.

You should find the external IP address in your cloud provider’s dashboard. Make sure that your network security settings allow traffic to this IP on the necessary ports.

Local Development & Testing

For local clusters, modify the hosts file. Add an entry to your operating system’s hosts file to map the hostname to your local machine’s IP address. The specific file to change and its location, though, depends on your operating system (see below).

Linux & macOS

When using a Unix based system like Linux or macOS, you’ll need to open the hosts file in the /etc directory, with administrative privileges like so:

sudo nano /etc/hosts

There you’ll have to add the following line at the end of the file:

127.0.0.1   keycloak.local

Windows

If you’re using a Windows system, you’ll instead need to start Notepad as an administrator. With it, open the hosts file, which is usually located at C:\Windows\System32\drivers\etc\hosts. Be careful when modifying system files while logged in as administrator, to avoid problems.

Add the following line to the end of that file:

127.0.0.1   keycloak.local

By adding this entry, keycloak.local resolves to 127.0.0.1, allowing your browser and applications to access Keycloak running on your local machine.

Use the same hostname — keycloak.local in this example — throughout your development environment to prevent configuration mismatches.

Create Administrator Account

Next you’ll need to create an administrator account with full access to Control Center’s features. Provide a name, an email address, and a password for the account.

Finalize Installation

Complete the setup by installing all necessary resources. This step configures Keycloak and ensures all dependencies are configured properly.

Log into Control Center

After the installation has been completed, click the Go to Dashboard button. You’ll be redirected to the Control Center login page.

Once there, enter the credentials for the administrator account you created. Then click Sign In to access Control Center. If you encounter any login problems, check that cookies and JavaScript are enabled in your browser.

Accessing Dashboard

Upon successful authentication, you’ll be taken to the Control Center dashboard, as shown in the screenshot here.

At this point, the dashboard should notify you that no applications are available. This is because none are deployed yet.

To start deploying your Vaadin applications and take full advantage of Control Center’s features, proceed to the Application Deployment documentation page.

Docs