Quick Start Guide

Follow this guide to quickly set up OpenChoreo in a local environment with Docker.

The setup uses a preconfigured Dev Container that includes all required dependencies for installation and cleanup.

⚙️ Prerequisites

Ensure the following before you begin:

• Docker (Engine 26.0+ recommended)
  • Allocate at least 4 GB RAM and 2 CPUs.
• Mac users: Use Colima for best compatibility

colima start --vm-type=vz --vz-rosetta --cpu 2 --memory 4

• 5–10 minutes of setup time

note

If you encounter issues with Docker alternatives (Docker Desktop, Rancher Desktop, etc.), report them via GitHub.

1

Start the Dev Container

Run the following command to start the dev container and open a terminal session within it:

docker run --rm -it --name openchoreo-quick-start \
--pull always \
-v /var/run/docker.sock:/var/run/docker.sock \
--network bridge \
-p 8443:8443 \
-p 7007:7007 \
ghcr.io/openchoreo/quick-start:v0.3.2

2

Install OpenChoreo

Inside the container, run the installation command:

./install.sh --openchoreo-version 0.3.2

This command performs the following:

• Creates a local KinD (Kubernetes-in-Docker) cluster
• Installs OpenChoreo and its dependencies using Helm charts.

tip

The installation script is idempotent. You can rerun it safely if the process is interrupted.

When installation completes successfully, you see a summary of component statuses:

tip

If any components remain in the pending state, wait a few minutes and run the following command to check their status:

./check-status.sh

3

Access the Developer Portal

The quickstart deployment includes a Backstage instance that acts as the developer portal for managing and visualizing OpenChoreo components. Once the backstage component is [READY], access it at:

🌐 Backstage Portal: http://localhost:7007

The Backstage portal provides:

• Cell Diagram: View deployed components and their relationships.
• Logs: Access build and runtime logs.
• Configure and Deploy: Manage configuration, deployment, and environment promotion

The portal automatically lists all components deployed through OpenChoreo, giving a unified view of the environment.

4

Deploy a Sample Web Application

After setting up OpenChoreo in your Docker environment, deploy a sample web application by running:

./deploy_web_application.sh

When deployment completes, the output includes a message with the application URL:

✅ Endpoint is ready!
🌍 You can now access the Sample Web Application at: https://react-starter-development.choreoapps.localhost:8443

Understanding the Setup

Running the installation and deployment commands initializes OpenChoreo locally and deploys a sample web application. The following sections describe what occurs behind the scenes.

1. The Install Command

The installation process:

• Initializes a Dev Container with all required tools.
• Creates a KinD (Kubernetes-in-Docker) cluster in Docker.
• Installs the OpenChoreo IDP and dependencies using Helm charts.

Foundation Resources Created

The installation automatically provisions the following OpenChoreo abstractions:

• Organization
• Data Plane
• Build Plane
• Environments (e.g., Development, Staging, Production)
• Deployment Pipeline
• Project

View these resources using the following commands:

kubectl get organizations
kubectl get dataplanes
kubectl get environments
kubectl get projects

View details for a specific resource:

kubectl get project default -oyaml

2. Deploy Command

The deployment script creates:

• A sample Web Application Component
• The corresponding Deployment resource

List deployed components:

kubectl get components

tip

Explore more examples in the Samples directory or in /samples inside the Dev Container.

important

When running samples in the Dev Container, you don’t need to expose the OpenChoreo Gateway manually; it’s already available on port 8443 of the host machine.

5

Cleaning up

After completing your work, choose one of the following options:

1. Exit and return later: Exit the Dev Container to resume work later:

    exit

2. Full cleanup: Remove all resources and restore a clean environment:

   ./uninstall.sh
   exit

This completes the setup and teardown process for OpenChoreo.

Troubleshooting

Docker Resource Constraints

If installation fails, confirm Docker has sufficient resources:

docker run --rm alpine:latest sh -c "echo 'Memory:'; free -h; echo; echo 'CPU Cores:'; nproc"

Ensure at least 4 GB RAM and 2 CPU cores are allocated.

Port Access Issues (Backstage and External Gateway)

If you're unable to access:

• Backstage at localhost:7007
• External Gateway at port 8443

Verify that socat processes are running inside the Dev Container:

ps aux | grep socat

socat handles port forwarding between the container and the host machine. If these processes are not running, re-run the installation command:

./install.sh --openchoreo-version 0.3.2

You have now set up OpenChoreo locally using a preconfigured environment, deployed a sample web application, and learned how to inspect, manage, and clean up the setup. This environment serves as a reproducible baseline for testing and evaluating OpenChoreo components and workflows.