How to Deploy dotCMS Using Helm Charts on Kubernetes

Deploying applications on Kubernetes can get complicated, especially when managing configuration files, containers, and services. That’s where Helm comes in. Helm is a package manager that simplifies Kubernetes deployments by using reusable templates called charts.

If you’re used to deploying applications with Docker or Docker Compose, Helm takes things several steps further:

Instead of hardcoding container specs, Helm templates allow dynamic and reusable configurations.
Helm integrates cleanly with GitOps workflows, making your deployments declarative and version-controlled.
You gain first-class Kubernetes resource management, including secrets, persistent volumes, autoscaling, and rolling upgrades, all baked into the Helm chart.

In this post, we’ll walk you through how to deploy dotCMS using Helm. Whether you’re running it locally for development or setting up a proof of concept, this guide will help you get started quickly and reliably.

Prerequisites

Before diving in, make sure you have the following tools installed on your local machine:

Docker Desktop (with Kubernetes enabled)
kubectl (Kubernetes command-line tool)
Helm (Kubernetes package manager)

Let’s install each one step by step (assuming you’re using macOS):

1. Docker Desktop

Download Docker Desktop from docker.com.

After installation:

Open Docker Desktop and go to Settings > Kubernetes
Enable Kubernetes
Apply the changes and wait for the cluster to start

2. kubectl

Install via Homebrew:

brew install kubectl

Verify installation:

kubectl version --client

Finally, verify your Kubernetes cluster is running:

kubectlcluster-info

3. Helm

Install via Homebrew:

brew install helm

Check it’s working:

helm version

Step-by-Step Deployment Instructions

Once the tools are installed and your local cluster is up, follow these steps to deploy dotCMS using the official Helm chart.

Step 1: Add the dotCMS Helm Repository

helm repo add dotcms https://dotcms.github.io/helm-charts/
helm repo update

You should get an output as follow:

"dotcms" has been added to your repositories

After updating, you can verify that the repository was added by listing all configured Helm repos:

helm repo list

You should see an entry like this:

NAME         URL
dotcms       https://dotcms.github.io/helm-charts/

Step 2: Install the dotCMS Helm Chart

Use the following command to install dotCMS into its own namespace (dotcms-dev):

helm install dotcms dotcms/dotcms --namespace dotcms-dev --create-namespace

Helm will fetch the chart, apply Kubernetes resources, and start the deployment.

Step 3: Verify the Deployment

Check if the pods are running:

kubectl get pods -n dotcms-dev

You should see output similar to the following:

NAME                               READY  STATUS   RESTARTS AGE
db-db7df7865-spvsf                  1/1   Running      1    9m

dotcms-dev-prod-post-upgrade-sw8zb  0/1   Completed    0    9m

dotcms-dev-prod-pre-upgrade-czmcs   0/1   Completed    0    9m

dotcms-dotcms-dev-prod-0            1/1   Running      1    9m

opensearch-5cf4989954-5v8gs         1/1   Running      1    9m

redis-65f547c55-w5cfj               1/1   Running      1    9m

Tip: Ensure your main dotCMS pod is in the Running state with 1/1 in the READY column. It's normal for pre/post-upgrade hooks to show as Completed.

If something doesn’t look right, you can get more info about a pod with:

kubectl describe pod <pod-name> -n dotcms-dev

Step 4: Access dotCMS Locally (Port Forwarding)

To open dotCMS in your browser, forward the port from the Kubernetes service:

1. List services to find the one called dotcms:


kubectl get svc -n dotcms-dev

You should see something similar to this:

NAME                 TYPE        CLUSTER-IP    EXTERNAL-IP  PORT(S)        AGE
db                   ClusterIP   10.103.100.39   <none>    5432/TCP        9m

dotcms-dev-prod-pp   ClusterIP   None            <none>    8080/TCP        9m 

dotcms-dev-prod-svc  NodePort    10.103.176.32   <none>    8082:30213/TCP  9m 

opensearch           ClusterIP   10.102.185.7    <none>  9200/TCP,9600/TCP 9m  

redis                ClusterIP   10.110.253.172  <none>    6379/TCP        9m

2. Forward port 8080 on your local machine to port 80 in the cluster:

kubectl port-forward svc/dotcms 8080:80 -n dotcms-dev

In most cases, you’ll want to forward port 8080 from your local machine to the service’s port inside the cluster. You can do this with:

kubectl port-forward svc/dotcms 8080:80 -n dotcms-dev

Tip: If your service has a different name or port mapping (e.g., NodePort instead of ClusterIP), adjust the service name and port accordingly.

Once the port is forwarded, open your web browser and visit:

http://localhost:8080/dotAdmin

You should see the dotCMS login screen.

Conclusion

Using Helm to deploy dotCMS simplifies what could otherwise be a complex Kubernetes setup. It gives you a repeatable, version-controlled way to manage deployments, perfect for GitOps workflows.

Compared to traditional Docker or Docker Compose approaches:

Helm enables native integration with Kubernetes, eliminating the need to manually define and manage pods, services, volumes, and networks.
Your configuration becomes declarative, enabling automation, consistency, and traceability across environments.
Features like rolling updates, parameterization, and rollback support come out of the box.

Whether you’re developing locally or preparing for a production deployment, Helm helps keep things clean, scalable, and ready for modern infrastructure practices.

Happy deploying!