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.
• If you plan to install with BuildPlane, allocate 8 GB RAM and 4 CPUs for optimal performance.
• 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=host \
  ghcr.io/openchoreo/quick-start:v0.4.0

2

Install OpenChoreo

Inside the container, run the installation command:

./install.sh --version 0.4.0

This command performs the following:

• Creates a local k3d (k3s-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

Deploy a Sample Web Application

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

./deploy-react-starter.sh

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

[SUCCESS] React Starter web application is ready!
🌍 Access the application at: http://react-starter-development.openchoreoapis.localhost:9080
Open this URL in your browser to see the React starter application.

[INFO] To clean up and delete this application, run:
[INFO] ./deploy-react-starter.sh --clean

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 k3d (k3s-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
• Component Types (e.g., service, web-application, scheduled-task)

View these resources using the following commands:

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

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 9080 (HTTP) and port 9443 (HTTPS) of the host machine.

Explore More

After deploying your first application, try these additional examples to explore more of OpenChoreo's capabilities:

GCP Microservices Demo

Deploy a complete microservices application with 11 services (frontend, cart, checkout, payment, etc.):

./deploy-gcp-demo.sh

This demonstrates how OpenChoreo handles multi-service applications and service-to-service communication.

Build and Deploy from Source

Experience the full development workflow by building a container image from source code and deploying it:

./build-deploy-greeter.sh

note

This example requires the Build Plane. If you didn't install it initially, reinstall with:

./install.sh --version 0.4.0 --with-build

This demonstrates:

• Building container images from source
• Storing images in the integrated container registry
• Deploying the built image to the Data Plane

4

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 (or 8 GB RAM and 4 CPU cores if using BuildPlane).

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.