# Get Started with Entando in 3 Easy Steps
New to Kubernetes, hypervisors, and Helm charts?
This in-depth guide takes a learn-as-you-go approach, and will give you a working knowledge of Kubernetes as you get Entando up and running in a local environment.
Note: For advanced or long-time Entando users, check out our Quick Reference install guide with just the steps.
# Install Kubernetes
Since Entando is designed to run on Kubernetes, let's get started by installing our own instance of Kubernetes locally.
We've tested a variety of Kubernetes implementations including Minikube, Minishift, CodeReady Containers, K3s, and Microk8s to find the best combination of low cpu/memory usage, fast startup times, and minimal configuration so we can get started quickly. After downloading the necessary files, we'll have our own instance of Kubernetes up and running in < 60 seconds.
What's Needed to Run Kubernetes
Kubernetes is a container orchestrator designed to manage a server cluster. It requires at least one master node running a Linux OS. We'll be using Multipass to create a lightweight Ubuntu VM in seconds that runs on a bare metal hypervisor for speed and performance.
# Enable Hypervisor
TIP
Hypervisors allow you to create and run virtual machines. Virtualization software that run on top of your operating system like VirtualBox or VMWare Workstation are Type 2 hypervisors. Type 1 hypervisors run on bare metal.
Let's install a bare metal hypervisor for optimal performance.
Mac: Install hyperkit
.
brew install hyperkit
Windows: Install Hyper-V (opens new window)
What if my machine doesn't support hyperkit or Hyper-V?
Use a Type 2 hypervisor that runs on top of your operating system:
- Install Virtual Box: Mac (opens new window) Windows (opens new window)
# Launch Ubuntu VM
TIP
Multipass is a tool developed by the publishers of Ubuntu to create lightweight Ubuntu VMs in seconds.
Install Multipass (opens new window)
Launch VM
multipass launch --name ubuntu-lts --cpus 4 --mem 8G --disk 20G
- Open a shell
multipass shell ubuntu-lts
# Run Kubernetes
TIP
K3s is a certified Kubernetes distribution designed for production workloads in resource-constrained environments.
It's packaged as a single <40MB binary that reduces the dependencies and steps needed to install, run and auto-update a production Kubernetes cluster.
- Install
k3s
curl -sfL https://get.k3s.io | sh -
- Check for
Ready
STATUS
.
sudo kubectl get node
What's running out of the box?
sudo kubectl get pods -A
Congratulations!
You now have a local instance of Kubernetes up and running.
# Prepare Kubernetes Environment
To install Entando, we'll add Custom Resources
, create a Namespace
, download a Helm
chart, and configure external access to our cluster.
# Add Custom Resources
TIP
Standard resources in Kubernetes include things like Pods
, which are a group of one or more containers, Services
, the way to call or access your pods, and Ingresses
, for managing external access to your cluster.
Custom resources let you store and retrieve structured data. (opens new window) Combining a custom resource with a custom controller allows you to define a desired state to automate the running of your applications or services in a Kubernetes cluster.
Examples of custom resources in Entando are:
Entando App Engine
Entando Identity Management System
From your Ubuntu shell:
- Download custom resource definitions.
wget -c https://developer.entando.com/assets/yaml/custom-resources.tar.gz -O - | tar -xz
- Create custom resources
sudo kubectl create -f custom-resources
# Create Namespace
TIP
You can use namespaces to allocate resources and set cpu/memory limits for individual projects or teams. They can also encapsulate projects from one another.
sudo kubectl create namespace entando
# Download Helm Chart
TIP
Helm is a package manager for Kubernetes that helps you define, install, and upgrade Kubernetes applications.
curl -L -C - -O https://developer.entando.com/assets/yaml/entando.yaml
# Configure Access to Your Cluster
TIP
Entando sets up Ingresses
in Kubernetes to access services from outside your server cluster. We'll use this to access Entando from a local browser.
To set up external access to your cluster, you'll need to replace the value of ENTANDO_DEFAULT_ROUTING_SUFFIX
with your Ubuntu IP. You can look up your Ubuntu IP, and edit the YAML file manaully, but running the below commands will automatically update the IP address for you.
IP=$(hostname -I | awk '{print $1}')
sed -i "s/192.168.64.25/$IP/" entando.yaml
# Deploy Entando
Deploying the Helm chart will deploy all of the Kubernetes resources required for Entando to run.
sudo kubectl create -f entando.yaml
sudo kubectl get pods -n entando --watch
What does a successful startup look like?
- First, you'll see the Entando operator:
ContainerCreating
>Running
- Next, the Entando composite app deployer:
Pending
>ContainerCreating
>Running
- Then, Keycloak:
kc-deployer
>kc-db-deployment
Jobs / Deployments
- Jobs, like
kc-db-preparation-job
run once, and areCompleted
:0/1
- Database deployments, like
kc-db-deployment
, should end up asRunning
:1/1
- The Keycloak server deployment
kc-server-deployment
, should end up asRunning
:1/1
- The
quickstart-server-deployment
should end up as3/3
Lifecycle Events
- Each line represents an event:
Pending
,ContainerCreating
,Running
orCompleted
- Restarts should ideally be
0
; otherwise, there was a problem with your cluster, and Kubernetes is trying to self-heal
ubuntu@test-vm:~$ sudo kubectl get pods -n entando --watch
NAME READY STATUS RESTARTS AGE
quickstart-operator-8556c9c6f8-9ghwg 0/1 ContainerCreating 0 3s
quickstart-operator-8556c9c6f8-9ghwg 0/1 Running 0 49s
quickstart-composite-app-deployer-picaju7bf0 0/1 Pending 0 0s
quickstart-composite-app-deployer-picaju7bf0 0/1 Pending 0 0s
quickstart-composite-app-deployer-picaju7bf0 0/1 ContainerCreating 0 0s
quickstart-composite-app-deployer-picaju7bf0 1/1 Running 0 20s
quickstart-kc-deployer-mx7ms3sc2l 0/1 Pending 0 0s
quickstart-kc-deployer-mx7ms3sc2l 0/1 Pending 0 0s
quickstart-kc-deployer-mx7ms3sc2l 0/1 ContainerCreating 0 0s
quickstart-operator-8556c9c6f8-9ghwg 1/1 Running 0 88s
quickstart-kc-deployer-mx7ms3sc2l 1/1 Running 0 19s
quickstart-kc-db-deployment-c57f75d7f-wxmqr 0/1 Pending 0 0s
quickstart-kc-db-deployment-c57f75d7f-wxmqr 0/1 Pending 0 7s
quickstart-kc-db-deployment-c57f75d7f-wxmqr 0/1 ContainerCreating 0 7s
quickstart-kc-db-deployment-c57f75d7f-wxmqr 0/1 Running 0 77s
quickstart-kc-db-deployment-c57f75d7f-wxmqr 1/1 Running 0 87s
quickstart-kc-db-preparation-job-1d6ab9b6-7 0/1 Pending 0 0s
quickstart-kc-db-preparation-job-1d6ab9b6-7 0/1 Pending 0 0s
quickstart-kc-db-preparation-job-1d6ab9b6-7 0/1 Init:0/1 0 0s
quickstart-kc-db-preparation-job-1d6ab9b6-7 0/1 Init:0/1 0 13s
quickstart-kc-db-preparation-job-1d6ab9b6-7 0/1 PodInitializing 0 15s
quickstart-kc-db-preparation-job-1d6ab9b6-7 0/1 Completed 0 17s
quickstart-kc-server-deployment-66484d596d-qr78q 0/1 Pending 0 0s
quickstart-kc-server-deployment-66484d596d-qr78q 0/1 Pending 0 0s
quickstart-kc-server-deployment-66484d596d-qr78q 0/1 ContainerCreating 0 0s
quickstart-kc-server-deployment-66484d596d-qr78q 0/1 Running 0 3m
quickstart-kc-server-deployment-66484d596d-qr78q 1/1 Running 0 4m36s
quickstart-kc-deployer-mx7ms3sc2l 0/1 Completed 0 6m50s
quickstart-eci-deployer-kx9nhop22g 0/1 Pending 0 0s
quickstart-eci-deployer-kx9nhop22g 0/1 Pending 0 0s
quickstart-eci-deployer-kx9nhop22g 0/1 ContainerCreating 0 0s
quickstart-eci-deployer-kx9nhop22g 1/1 Running 0 5s
quickstart-eci-k8s-svc-deployment-7c58c78b55-z52xj 0/1 Pending 0 0s
quickstart-eci-k8s-svc-deployment-7c58c78b55-z52xj 0/1 Pending 0 0s
quickstart-eci-k8s-svc-deployment-7c58c78b55-z52xj 0/1 ContainerCreating 0 0s
quickstart-eci-k8s-svc-deployment-7c58c78b55-z52xj 0/1 Running 0 97s
quickstart-eci-k8s-svc-deployment-7c58c78b55-z52xj 1/1 Running 0 2m7s
quickstart-eci-deployer-kx9nhop22g 0/1 Completed 0 2m15s
quickstart-deployer-os19rw3eto 0/1 Pending 0 0s
quickstart-deployer-os19rw3eto 0/1 Pending 0 0s
quickstart-deployer-os19rw3eto 0/1 ContainerCreating 0 1s
quickstart-deployer-os19rw3eto 1/1 Running 0 6s
quickstart-db-deployment-7fff4c8479-qf469 0/1 Pending 0 0s
quickstart-db-deployment-7fff4c8479-qf469 0/1 Pending 0 4s
quickstart-db-deployment-7fff4c8479-qf469 0/1 ContainerCreating 0 4s
quickstart-db-deployment-7fff4c8479-qf469 0/1 Running 0 7s
quickstart-db-deployment-7fff4c8479-qf469 1/1 Running 0 19s
quickstart-db-preparation-job-5a55b267-6 0/1 Pending 0 0s
quickstart-db-preparation-job-5a55b267-6 0/1 Pending 0 0s
quickstart-db-preparation-job-5a55b267-6 0/1 Init:0/4 0 0s
quickstart-db-preparation-job-5a55b267-6 0/1 Init:0/4 0 4s
quickstart-db-preparation-job-5a55b267-6 0/1 Init:1/4 0 5s
quickstart-db-preparation-job-5a55b267-6 0/1 Init:1/4 0 8s
quickstart-db-preparation-job-5a55b267-6 0/1 Init:2/4 0 9s
quickstart-db-preparation-job-5a55b267-6 0/1 Init:2/4 0 6m42s
quickstart-db-preparation-job-5a55b267-6 0/1 Init:3/4 0 7m20s
quickstart-db-preparation-job-5a55b267-6 0/1 Init:3/4 0 7m22s
quickstart-db-preparation-job-5a55b267-6 0/1 PodInitializing 0 7m23s
quickstart-db-preparation-job-5a55b267-6 0/1 Completed 0 7m25s
quickstart-server-deployment-5597597575-gtptz 0/3 Pending 0 0s
quickstart-server-deployment-5597597575-gtptz 0/3 Pending 0 4s
quickstart-server-deployment-5597597575-gtptz 0/3 ContainerCreating 0 4s
quickstart-server-deployment-5597597575-gtptz 0/3 Running 0 2m35s
quickstart-server-deployment-5597597575-gtptz 1/3 Running 0 2m37s
quickstart-server-deployment-5597597575-gtptz 2/3 Running 0 2m38s
quickstart-server-deployment-5597597575-gtptz 3/3 Running 0 3m5s
quickstart-deployer-os19rw3eto 0/1 Completed 0 11m
quickstart-composite-app-deployer-picaju7bf0 0/1 Completed 0 20m
Press Ctrl-C
to exit the watch command once everything is up and running.
What pods come out of the box?
sudo kubectl get pods -n entando
NAME READY STATUS RESTARTS AGE
quickstart-operator-8556c9c6f8-9ghwg 1/1 Running 0 132m
quickstart-kc-db-deployment-c57f75d7f-wxmqr 1/1 Running 0 130m
quickstart-kc-db-preparation-job-1d6ab9b6-7 0/1 Completed 0 129m
quickstart-kc-server-deployment-66484d596d-qr78q 1/1 Running 0 128m
quickstart-kc-deployer-mx7ms3sc2l 0/1 Completed 0 130m
quickstart-eci-k8s-svc-deployment-7c58c78b55-z52xj 1/1 Running 0 123m
quickstart-eci-deployer-kx9nhop22g 0/1 Completed 0 124m
quickstart-db-deployment-7fff4c8479-qf469 1/1 Running 0 121m
quickstart-db-preparation-job-5a55b267-6 0/1 Completed 0 121m
quickstart-server-deployment-5597597575-gtptz 3/3 Running 0 113m
quickstart-deployer-os19rw3eto 0/1 Completed 0 121m
quickstart-composite-app-deployer-picaju7bf0 0/1 Completed 0 131m
# Log in to Entando
Now that we've installed Entando, let's log in to Entando App Builder
.
Get the URL to access Entando from your local browser.
sudo kubectl get ingress -n entando -o jsonpath=\
'{.items[2].spec.rules[*].host}{.items[2].spec.rules[*].http.paths[2].path}{"\n"}'
- Example URL:
quickstart-entando.192.168.64.33.nip.io/app-builder/
- Username: admin
- Password: adminadmin
After login, change your password to activate your account.
- Note: If the login process hangs for more than 5 seconds, refresh the browser.
The App Builder is where we'll compose our micro frontends alongside CMS pages and content.
Congratulations!
We now have Entando up and running on Kubernetes in our local environment.