Quick Start

Development Preview

This local setup is under active development and intended for evaluation and development purposes only. The local environment differs from production deployments in architecture, security configuration, and scalability.

Track progress and upcoming improvements on our project dashboard.

1. Clone the Repository

git clone https://github.com/platform-mesh/helm-charts.git
cd helm-charts/local-setup

2. Run the Setup

The setup script automates the entire bootstrap process. Choose one of the following options:

Standard Setup

Task

# Full setup (deletes existing cluster and creates new one)
task local-setup

# Iterate on existing cluster (faster, preserves cluster state)
task local-setup:iterate

Script

# Full setup (deletes existing cluster and creates new one)
kind delete cluster --name platform-mesh
./scripts/start.sh

# Iterate on existing cluster (faster, preserves cluster state)
./scripts/start.sh

After the script is finished, it should print Installation Complete ♥ ! along with instructions on accessing the portal.

Cached Setup (Faster)

Image caching speeds up cluster recreation by using local Docker registry mirrors. The setup script automatically starts the required registry proxies when using cached mode.

Task

# Setup image proxies (run only once)
task local-setup-start-docker-registries

# Full setup with caching
task local-setup:cached

# Iterate on existing cluster
task local-setup:cached:iterate

Script

# Full setup with caching
kind delete cluster --name platform-mesh
./scripts/start.sh --cached

# Iterate on existing cluster
./scripts/start.sh --cached

Setup Duration

The initial setup typically takes 5-10 minutes, depending on your internet connection and machine performance.

3. Configure Local DNS

Add the following entries to your /etc/hosts file:

127.0.0.1 portal.dev.local kcp.api.portal.dev.local

WSL Users

Also add these entries to the Windows hosts file at C:\Windows\System32\drivers\etc\hosts

Organization Subdomains

Each created organization gets its own subdomain (e.g., <organization-name>.portal.dev.local) that must be added to your /etc/hosts file:

127.0.0.1 <organization-name>.portal.dev.local

Remember to add a hosts entry for every organization you create in the platform.

4. Access the Services

Once the setup is complete, you can access:

• Onboarding Portal: https://portal.dev.local:8443
• KCP API: https://kcp.api.portal.dev.local:8443

Certificate Trust

You may need to trust the local certificates generated by mkcert. The setup script will attempt to do this automatically, but you may need to manually trust them in your browser or system keychain.

For detailed certificate trust instructions for different platforms (WSL2, Windows, Linux), see the troubleshooting section below.

What's Installed?

The local setup deploys the following components:

Prerequisites

• Docker: containers
  • kindest/node:v1.34.0 for KIND
  • 3 registry:2 images if the cached task was used
• Flux: GitOps toolkit for continuous delivery
• KRO: Kubernetes Resource Orchestrator
• OCM Controller: Open Cluster Management controller

Platform Mesh

The Platform Mesh Operator is the core component that deploys and manages all Platform Mesh infrastructure. The complete list of components for a given version is defined in the OCM (Open Component Model) component descriptor.

You can view the Platform Mesh components using:

ocm get componentversions --repo ghcr.io/platform-mesh github.com/platform-mesh/platform-mesh --latest -oyaml

Installing the OCM CLI

If you don't have the OCM CLI installed, you can install it using one of the following methods:

macOS (Homebrew):

brew install open-component-model/tap/ocm

Linux/macOS (Script):

curl -s https://ocm.software/install.sh | bash

Manual Installation: Download the binary for your platform from the OCM releases page.

For more installation options and details, see the OCM installation documentation.

Key components deployed by the operator include:

• Portal: A example implementation of a Portal UI based on Platform Mesh
• Kubernetes GraphQL Gateway: Generic Grahqpl Gateway that offers a Graphql api for the underlying KCP Control Plane
• KCP: Manages Kubernetes-based control planes
• OpenFGA: Central Relationship based Authorization system
• Keycloak: Default Identity Provider used for authentication
• Account Controller: Handles multi-tenancy and management of accounts and organization
• Extension Controller: Handles Micro Frontend configurations and validations

Example Component Structure (YAML)

component:
  name: github.com/platform-mesh/platform-mesh
  version: <version>
  provider:
    name: platform-mesh
  resources:
    - componentName: github.com/platform-mesh/account-operator
      name: account-operator
      version: <version>
    - componentName: github.com/crossplane/crossplane
      name: crossplane
      version: <version>
    - componentName: github.com/gardener/etcd-druid
      name: etcd-druid
      version: <version>
    - componentName: github.com/platform-mesh/extension-manager-operator
      name: extension-manager-operator
      version: <version>
    - componentName: github.com/platform-mesh/infra
      name: infra
      version: <version>
    - componentName: github.com/platform-mesh/keycloak
      name: keycloak
      version: <version>
    - componentName: github.com/kcp-dev/kcp-operator
      name: kcp-operator
      version: <version>
    # ... additional components

For the complete and up-to-date component list, always refer to the OCM component descriptor using the command above.

How It Works

The setup script automates the entire bootstrap process:

1. Environment Validation - Checks for required dependencies and system compatibility
2. Cluster Creation - Creates a Kind cluster with the necessary configuration
3. Certificate Setup - Generates local SSL certificates for secure access
4. Platform Mesh Prerequisites - Installs Flux, KRO, and OCM
5. Platform Mesh Installation - Deploys the Platform Mesh operator and components
6. Post-Install Configuration - Creates KCP kubeconfig and validates readiness

The Platform Mesh operator manages the actual component deployment by reconciling the PlatformMesh custom resource. For detailed information about the bootstrap process and operator API, see:

• Platform Mesh Operator - Operator documentation and API reference