Developer Guide Overview

This guide is for the people who ship software on DevsPortal: the application developers — the builders. If you write a service, a web app, a worker, or a scheduled job and you want it running in dev, staging, and production without filing a ticket for a namespace, a pipeline, or a load balancer, this guide is for you.

DevsPortal is a self-service internal developer platform. You describe what you want to run; the platform decides how it runs — which cluster, which network policies, which gateway, which TLS certificate. The golden paths your platform engineers set up are already there. Your job is to use them.

Which persona am I?

This guide is the Developer track — the end user of the IDP. The infrastructure under you is run by the Platform Admin, and the projects, access, and golden-path templates you use are set up by the Platform Engineer.

note

DevsPortal is built on the Control Plane Operator engine. Throughout this guide you'll see identifiers like openchoreo.dev/v1alpha1, the occ CLI, and namespaces such as openchoreo-control-plane. These are unchanged internal names from the engine — they are not rebranded, and you can use them exactly as written.

Everything in this guide is grounded in the Fedshi instance — customer #1 and the live reference deployment. You sign in at https://console.idp.fedshi.com, the CLI talks to https://api.idp.fedshi.com, and your apps land on {fedshi.apps}. If you run a different DevsPortal instance, swap those hostnames for your own; the workflow is identical.

The mental model: Project → Component → Workload

Three abstractions carry almost everything you do. Learn these and the rest of the platform clicks into place.

Abstraction	What it is	Fedshi example
Project	A bounded context — a logical group of related components that together deliver a business capability. Each Project becomes an isolated runtime cell (its own namespace and network policies) and is tied to a deployment pipeline.	checkout — the cart, payment, and order-history services that make up Fedshi's checkout flow
Component	A single deployable unit inside a Project: a service, a web app, a worker, or a scheduled task. A Component picks a ComponentType (a platform-defined template) that governs how it deploys.	cart-api, a backend service in the checkout project
Workload	The runtime contract of a Component: which container image to run, which endpoints it exposes, and which other components or resources it depends on.	The cart-api image, its HTTP endpoint on port 8080, and its dependency on a Postgres Resource

The hierarchy nests cleanly:

Project (checkout)            → a runtime cell
└── Component (cart-api)      → picks a ComponentType
    └── Workload              → image + endpoints + dependencies
        ├── Endpoint (http)   → an exposed interface + visibility
        └── Dependency        → another component's endpoint, or a Resource

When you deploy, the platform snapshots your Component into an immutable ComponentRelease, binds that release to an Environment (dev → staging → prod), applies any per-environment overrides, and renders the final Kubernetes resources onto a data plane. You promote the same release up the pipeline — what you tested in dev is byte-for-byte what reaches production. The full chain is covered in Deploy and promote; the abstractions themselves are defined in Concepts.

What you actually do, day to day

• Get in. Sign in to the console, or point the occ CLI at the Fedshi control plane. See Getting access.
• Create a Project and a Component. Group related services, pick a ComponentType, point it at your repo or a prebuilt image. See Projects and components.
• Define the Workload. Declare the image, the endpoints you expose, and how visible each one is. See Workloads and endpoints.
• Wire up dependencies. Consume another service's endpoint or a managed database, and let the platform inject the connection details for you. See Dependencies.
• Build from source. Let the platform build your container image on every git push. See Builds and CI.
• Deploy and promote. Ship to dev, then promote up to staging and prod through the pipeline, with per-environment overrides. See Deploy and promote.
• Watch it run. Read logs, metrics, and traces, and troubleshoot from the portal. See Observability.

Two ways to work: the portal and the CLI

Everything you can do, you can do two ways:

• The portal — the Fedshi developer console at https://console.idp.fedshi.com, a Backstage-based UI with a software catalog, guided "create" wizards, deploy/promote controls, and live logs. Best for discovery, onboarding, and day-to-day clicking. See Portal guide.
• The occ CLI — the command line for scripting, automation, and CI. Best when you want repeatability or you live in a terminal. See CLI reference.

Both talk to the same API and produce the same resources, so you can move between them freely — create a component in the UI, then deploy it from a script, then check its logs back in the console.

Where to start

If you want to…	Go to
Ship something in ten minutes	Quickstart
Understand the abstractions first	Concepts and Glossary
Get your login and CLI working	Getting access
Bring your whole team on board	Teams overview

New here? The fastest way to build intuition is to deploy a real component end to end — head straight to the Quickstart. If you want the field-by-field API detail behind any of these abstractions, the upstream Control Plane Operator concept reference goes deeper than this guide does.