🖼️ See the drawing + lab 🏠 Course home 🌿 Branch on GitHub ✏️ View source

🖼️ आकृती आणि labThe drawing + lab पूर्ण पानावर उघडा ↗Open full page ↗

🏛️ धडा 12 — Developer portal आणि संपूर्ण चित्र: एक स्वागत कक्ष

📍 तुम्ही इथे आहात: 12 पैकी धडा 12 · मागील: lesson-11-measuring · शेवटचा धडा 🎓

📦 या ब्रँचमध्ये काय आहे

धडे 01–11, आणि internal developer portal: प्रत्येक service चे एक पान, जे कार्यालयाच्या बाकीच्या भागांना माहीत असलेले सगळे गोळा करते — owner, dependencies आणि dependents (धडा 04), scorecard (10), policy findings (09), pipeline version (07), preview environments (06) आणि DORA आकडे (11). आणि कोर्सचा संपूर्ण नकाशा. portal_page() idp/guard.py मध्ये, portal() idp/demo.py मध्ये.

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

सुविधा कार्यालय मोठे झाले आहे: kit चे कपाट, नोंदवही, menu, चाचणी वर्गखोल्या, नेहमीच्या कामांची cards, किल्ल्यांचे कपाट, सुरक्षा तपासणी-यादी, तयारी-cards आणि आकड्यांची वही. नव्या शिक्षिकेला ती सगळी शोधायलाच नकाशा लागेल.

म्हणून दीपिका एक स्वागत कक्ष सुरू करते. 🏛️ कतरिना तिथे येते आणि म्हणते "exam-results". कक्ष एक पान दाखवतो:

owner: science · results database आणि sign-in system वर अवलंबून
parent portal तिच्यावर अवलंबून आहे
तयारी-card: 92%, gold — पुढे: पालकांना दिलेले वचन लिहा
सुरक्षा तपासणी-यादी: एक इशारा — "photo box public आहे → तो private करा आणि display kit वापरा"
नेहमीच्या कामाचे card: v2 → आज याचा अर्थ v2.1.0
आठवड्याला 3 बदल, कल्पनेपासून चालू होईपर्यंत 5 तास, 8% बिघडतात, दुरुस्तीला 2 तास

स्वागत कक्ष स्वतः काम करत नाही. ते kits, menu आणि कपाट करतात. कक्ष त्यांना एका जागी, सगळ्यांसाठी एकाच पद्धतीने, सहज सापडतील असे करतो.

🗺️ आकृती

flowchart LR
    cat["📇 catalog (04)"] --> p["🏛️ portal page<br/>exam-results"]
    sc["🏅 scorecard (10)<br/>92% gold"] --> p
    po["🛡️ policy (09)<br/>1 warning"] --> p
    pi["🚚 pipeline (07)<br/>v2 → v2.1.0"] --> p
    pr["🧪 previews (06)"] --> p
    do["📊 DORA (11)<br/>3.0/week · 5.0 h"] --> p
    p --> t["🛤️ templates (03) and<br/>self-service (05, 08)<br/>one click away"]

🗺️ काढलेली आवृत्ती + एक lab: https://school-edh.pages.dev/platform-engineering/lesson-diagrams.html#l12

❓ काय

Internal developer portal — platform चा user interface: एक website जिथे developers ना services, docs, owners, templates आणि self-service actions सापडतात. Portal म्हणजे platform नाही; तो त्याचा स्वागत कक्ष आहे. Platform फक्त CLI आणि templates सह अस्तित्वात असू शकतो; मागे काहीच नसलेला portal म्हणजे फक्त सुंदर catalog.
Backstage — developer portals बनवण्यासाठीचा open-source framework, Spotify मध्ये बनलेला, 2020 मध्ये open-source झालेला आणि आता CNCF incubating project. त्याची मुख्य features आहेत Software Catalog, Software Templates (scaffolder), TechDocs (docs-like-code, MkDocs ने बनवलेले) आणि Search, आणि तो plugins ने वाढवला जातो (Kubernetes, CI, cost, scorecards …). तो तुम्हालाच चालवावा आणि सांभाळावा लागतो — तो framework आहे, तयार product नाही.
Commercial portals — Port, Cortex, OpsLevel आणि इतर catalog, scorecards आणि self-service actions असलेला hosted portal देतात. Port entities ना blueprints म्हणून मांडतो. अनेक vendors hosted किंवा supported Backstage पण विकतात (उदाहरणार्थ Red Hat Developer Hub).
Single pane of glass — एकच पान सगळे दाखवेल हे वचन. प्रत्येक भागामागचा data ताजा असेल तरच ते खरे ठरते; जुना data दाखवणारा portal नसलेल्या portal पेक्षाही वाईट, कारण लोक त्यावर विश्वास ठेवतात.
Platform maturity — CNCF Platform Engineering Maturity Model (2023) investment, adoption, interfaces, operations आणि measurement यांमधील टप्प्यांचे वर्णन करतो. ते चर्चेचे साधन आहे, पूर्ण करायची checklist नाही.

🤔 का

कारण कार्यालयाच्या प्रत्येक भागाने एक प्रश्न सोडवला, आणि सगळ्यांनी मिळून एक नवा प्रश्न निर्माण केला: पाहायला खूप जागा. Portal platform ला असे बनवतो की नवी सहकारी पहिल्याच दिवशी ते शोधू शकते. प्रत्येक team आपली service पाहत असतानाच तो तिला तिच्या स्वतःच्या उणिवा (scorecard, warnings) दाखवतो. Portal शेवटी बनवणे हे जाणूनबुजून आहे: portal त्यामागच्या catalog, templates आणि data इतकाच चांगला असतो.

🔧 कसे (या repo मध्ये)

idp/guard.py मधील portal_page(name, catalog, passed, manifest, pipeline_ref, previews_live, deploys, weeks, resolve) आधीच्या प्रत्येक धड्यातील भाग call करतो: owner, dependencies आणि dependents साठी Catalog, card साठी score(), warnings साठी audit mode मध्ये evaluate(), pipeline साठी resolve_ref(), आणि आकड्यांसाठी dora(). तो सहा ओळी परत देतो — तेच पान. idp/demo.py मधील portal() exam-results चे पान छापतो.

🧪 करून पाहा

python3 idp/demo.py portal
python3 - <<'EOF'
import sys; sys.path.insert(0, "idp"); from demo import school_catalog, AFTER, BEFORE
from guard import CHECKS, portal_page; from selfserve import resolve_ref
c = school_catalog()
passed = {n for n, _ in CHECKS} - {"SLO written", "has a runbook"}
m = dict(labels={"owner": "maths"}, image="timetable:latest", limits={"cpu": "250m", "memory": "128Mi"}, env="production", replicas=2)
for line in portal_page("timetable", c, passed, m, "v2.0.0", 0, BEFORE, 4, resolve_ref): print(line)
EOF
python3 idp/demo.py
python3 idp/test_idp.py

✅ तपासा — तुम्हाला काय दिसायला हवे

portal हे छापते:

── the portal page for exam-results (one place, gathered from every part of the office):
   owner science · lifecycle production · depends on results-db, auth
   depended on by parent-portal
   scorecard 92% (gold) · next: SLO written
   policy: allowed with warnings · bucket is public → set public_bucket: false and serve files through the CDN kit
   pipeline v2 → v2.1.0 · preview environments live: 1
   DORA: 3.0 deploys/week · lead time 5.0 h · failure rate 8% · recovery 2.0 h

तुमचा snippet हे छापतो:

owner maths · lifecycle production · depends on auth
depended on by parent-portal
scorecard 83% (silver) · next: has a runbook
policy: allowed with warnings · image tag is 'latest' or missing → pin a version such as :1.4.2 (the paved pipeline tags every build)
pipeline v2.0.0 → v2.0.0 · preview environments live: 0
DORA: 1.0 deploys/week · lead time 150.0 h · failure rate 50% · recovery 23.0 h

पूर्ण run ✅ done — every teacher has a classroom ने संपतो, आणि tests 12/12 passed ने.

🏁 तुम्ही आत्ताच काय सिद्ध केले

एका function call ने सहा धड्यांची उत्तरे गोळा केली. Timetable चे पान maths team ला कोणीही report न लिहिता तीन कामे सांगते: runbook जोडा, image pin करा, आणि v2.0.0 वरून @v2 वर जाण्याचा विचार करा. त्याची DORA ओळ ("before" data वापरून) ती कुठून सुरुवात करेल ते दाखवते. पानावरचे प्रत्येक value कार्यालयाच्या स्वतंत्रपणे काम करणाऱ्या एखाद्या भागातून आले; portal ते फक्त वाचतो. हीच रचना आहे: portal हा स्वागत कक्ष आहे, कार्यालय नाही.

⚠️ नेहमीच्या चुका

catalog, templates आणि self-service अस्तित्वात येण्याआधीच portal ने सुरुवात करणे
Backstage ला एकदा install करायचे product समजणे — तो framework आहे ज्याला एक team लागते
जुन्या data ने भरलेला portal — लोक त्यावर विश्वास ठेवणे थांबवतात, मग तो वापरणेही थांबवतात
एकमेव जागा न बनता पाहण्याची आणखी एक जागा: tools ना link करा, त्यांची copy करू नका
portal ने teams चे काय वाचवले (धडा 11) यावरून न मोजता page views वरून मोजणे

🏭 प्रत्यक्ष वापरात

खऱ्या machine वर Backstage app सुरू करणे (Node.js आणि Yarn लागतात):

npx @backstage/create-app@latest          # asks for a name, creates the app
cd school-portal && yarn start            # recent templates start frontend + backend (older ones used yarn dev)

धडा 04 मधील catalog files app-config.yaml मध्ये register करणे:

catalog:
  locations:
    - type: url
      target: https://github.com/school/exam-results/blob/main/catalog-info.yaml
    - type: url
      target: https://github.com/school/paved-road/blob/main/templates/python-service/template.yaml
      rules:
        - allow: [Template]

Service ला तिच्या docs (TechDocs) आणि CI शी जोडणे तिच्या catalog-info.yaml मधील annotations ने होते, जसे backstage.io/techdocs-ref: dir:. आणि github.com/project-slug: school/exam-results.

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: platform च्या प्रत्येक इतर भागाप्रमाणे portal लाही owner, roadmap आणि users द्या (धडा 02). तोही एक product आहे.

🎓 प्रत्येक शिक्षिकेला वर्गखोली आहे

कामांच्या ओझ्याखाली बुडालेल्या teams आणि वाढती ticket ची रांग → product प्रमाणे चालवलेला platform, सर्वात मोठ्या त्रासापासून सुरुवात करून बनवलेला → service योग्य पद्धतीने सुरू करणारे golden-path templates → प्रत्येक owner आणि blast radius माहीत असलेला catalog → quotas मधले self-service resources → स्वतःहून साफ होणारी preview environments → एकच versioned pipeline रस्ता → versions आणि स्पष्टीकरणांसह secrets आणि config → दुरुस्ती कशी करायची ते सांगणारे guardrails → पुढची पायरी देणारे scorecards → लोकांनाही विचारून केलेले प्रामाणिक मोजमाप → आणि सगळे एकत्र आणणारा एक स्वागत कक्ष. तुम्ही फक्त platform engineering शिकला नाहीत — तुम्ही कोणत्याही team चा दिवस पाहून योग्य प्रश्न विचारू शकता: ते कशाची वाट पाहत आहेत, ते काय पुन्हा पुन्हा बनवत आहेत, आणि सुरक्षित मार्गाला सोपा मार्ग काय बनवेल? 🛤️🏛️🎓

⏭️ पुढे

इतर शाळा. CI/CD शाळा pipelines मध्ये खोलवर जाते; Argo CD शाळा GitOps delivery आणि ApplicationSets वर; Kubernetes शाळा बहुतेक platforms ज्यावर चालतात त्यावर; Observability शाळा alerts आणि dashboards kits वर; Security शाळा guardrails ज्याचे रक्षण करतात त्यावर; School portal मध्ये बाकी सगळे आहे.

git checkout main
python3 idp/demo.py     # one last run, for fun

🏛️ Lesson 12 — The developer portal & the whole picture: one front desk

📍 You are here: Lesson 12 of 12 · Previous: lesson-11-measuring · The last lesson 🎓

📦 What's in this branch

Lessons 01–11, plus the internal developer portal: one page per service that gathers what the rest of the office knows — owner, dependencies and dependents (lesson 04), scorecard (10), policy findings (09), pipeline version (07), preview environments (06) and DORA numbers (11). And the whole map of the course. portal_page() in idp/guard.py, portal() in idp/demo.py.

🧒 Explain like I'm 5

The facilities office has grown: a kit shelf, a register, a menu, trial rooms, routine cards, a key cabinet, a safety checklist, readiness cards and a notebook of numbers. A new teacher would need a map just to find them.

So Dipika opens a front desk. 🏛️ Katrina walks up and says "exam-results". The desk shows one page:

owner: science · depends on the results database and the sign-in system
the parent portal depends on it
readiness card: 92%, gold — next: write the promise to parents
safety checklist: one warning — "the photo box is public → make it private and use the display kit"
routine card: v2 → today that means v2.1.0
3 changes a week, 5 hours from idea to live, 8% break, 2 hours to fix

The front desk does not do the work. The kits, the menu and the cabinet do that. The desk makes them easy to find, in one place, the same way for everyone.

🗺️ Diagram

flowchart LR
    cat["📇 catalog (04)"] --> p["🏛️ portal page<br/>exam-results"]
    sc["🏅 scorecard (10)<br/>92% gold"] --> p
    po["🛡️ policy (09)<br/>1 warning"] --> p
    pi["🚚 pipeline (07)<br/>v2 → v2.1.0"] --> p
    pr["🧪 previews (06)"] --> p
    do["📊 DORA (11)<br/>3.0/week · 5.0 h"] --> p
    p --> t["🛤️ templates (03) and<br/>self-service (05, 08)<br/>one click away"]

🗺️ Drawn version + a lab: https://school-edh.pages.dev/platform-engineering/lesson-diagrams.html#l12

❓ What

Internal developer portal — the user interface of the platform: a website where developers find services, docs, owners, templates and self-service actions. The portal is not the platform; it is the front desk of it. A platform can exist with only a CLI and templates; a portal with nothing behind it is a pretty catalog.
Backstage — an open-source framework for building developer portals, created at Spotify, open-sourced in 2020 and now a CNCF incubating project. Its core features are the Software Catalog, Software Templates (the scaffolder), TechDocs (docs-like-code, built with MkDocs) and Search, and it is extended with plugins (Kubernetes, CI, cost, scorecards …). You run and maintain it yourself — it is a framework, not a finished product.
Commercial portals — Port, Cortex, OpsLevel and others offer a hosted portal with a catalog, scorecards and self-service actions. Port models entities as blueprints. Several vendors also sell hosted or supported Backstage (for example Red Hat Developer Hub).
Single pane of glass — the promise that one page shows everything. It only holds if the data behind each part is fresh; a portal showing stale data is worse than none, because people trust it.
Platform maturity — the CNCF Platform Engineering Maturity Model (2023) describes stages across investment, adoption, interfaces, operations and measurement. It is a conversation tool, not a checklist to finish.

🤔 Why

Because each part of the office solved a problem, and together they created a new one: too many places to look. The portal turns the platform into something a new teammate can discover on day one. It also shows each team its own gaps (scorecard, warnings) at the moment it is looking at its service. Building the portal last is deliberate: a portal is only as good as the catalog, templates and data behind it.

🔧 How (in this repo)

portal_page(name, catalog, passed, manifest, pipeline_ref, previews_live, deploys, weeks, resolve) in idp/guard.py calls the pieces from every earlier lesson: Catalog for owner, dependencies and dependents, score() for the card, evaluate() in audit mode for warnings, resolve_ref() for the pipeline, and dora() for the numbers. It returns six lines — the page. portal() in idp/demo.py prints the page for exam-results.

🧪 Try it

python3 idp/demo.py portal
python3 - <<'EOF'
import sys; sys.path.insert(0, "idp"); from demo import school_catalog, AFTER, BEFORE
from guard import CHECKS, portal_page; from selfserve import resolve_ref
c = school_catalog()
passed = {n for n, _ in CHECKS} - {"SLO written", "has a runbook"}
m = dict(labels={"owner": "maths"}, image="timetable:latest", limits={"cpu": "250m", "memory": "128Mi"}, env="production", replicas=2)
for line in portal_page("timetable", c, passed, m, "v2.0.0", 0, BEFORE, 4, resolve_ref): print(line)
EOF
python3 idp/demo.py
python3 idp/test_idp.py

✅ Verify — what you should see

portal prints:

── the portal page for exam-results (one place, gathered from every part of the office):
   owner science · lifecycle production · depends on results-db, auth
   depended on by parent-portal
   scorecard 92% (gold) · next: SLO written
   policy: allowed with warnings · bucket is public → set public_bucket: false and serve files through the CDN kit
   pipeline v2 → v2.1.0 · preview environments live: 1
   DORA: 3.0 deploys/week · lead time 5.0 h · failure rate 8% · recovery 2.0 h

Your snippet prints:

owner maths · lifecycle production · depends on auth
depended on by parent-portal
scorecard 83% (silver) · next: has a runbook
policy: allowed with warnings · image tag is 'latest' or missing → pin a version such as :1.4.2 (the paved pipeline tags every build)
pipeline v2.0.0 → v2.0.0 · preview environments live: 0
DORA: 1.0 deploys/week · lead time 150.0 h · failure rate 50% · recovery 23.0 h

The full run ends with ✅ done — every teacher has a classroom, and the tests with 12/12 passed.

🏁 What you just proved

One function call gathered six lessons' worth of answers. The timetable page tells the maths team three things to do without anyone writing them a report: add a runbook, pin the image, and consider moving from v2.0.0 to @v2. Its DORA line (using the "before" data) shows where it would start. Every value on the page came from a part of the office that works on its own; the portal only reads them. That is the design: the portal is the front desk, not the office.

⚠️ Common mistakes

starting with the portal before the catalog, templates and self-service exist
treating Backstage as a product to install once — it is a framework that needs a team
a portal full of stale data — people stop trusting it, then stop using it
one more place to look instead of the place: link out to the tools, do not copy them
measuring the portal by page views instead of by what it saved teams (lesson 11)

🏭 In production

Starting a Backstage app on a real machine (Node.js and Yarn required):

npx @backstage/create-app@latest          # asks for a name, creates the app
cd school-portal && yarn start            # recent templates start frontend + backend (older ones used yarn dev)

Registering the catalog files from lesson 04, in app-config.yaml:

catalog:
  locations:
    - type: url
      target: https://github.com/school/exam-results/blob/main/catalog-info.yaml
    - type: url
      target: https://github.com/school/paved-road/blob/main/templates/python-service/template.yaml
      rules:
        - allow: [Template]

Linking a service to its docs (TechDocs) and CI is done with annotations in its catalog-info.yaml, such as backstage.io/techdocs-ref: dir:. and github.com/project-slug: school/exam-results.

🏭 Why this matters in production: give the portal an owner, a roadmap and users, like every other part of the platform (lesson 02). It is a product too.

🎓 Every teacher has a classroom

Teams drowning in concerns and a growing ticket line → a platform run as a product, built from the biggest pain down → golden-path templates that start a service right → a catalog that knows every owner and the blast radius → self-service resources within quotas → preview environments that clean up after themselves → one versioned pipeline road → secrets and config with versions and explanations → guardrails that say how to fix → scorecards that give the next step → honest measures, with people asked too → and one front desk that gathers it all. You didn't just learn platform engineering — you can look at any team's day and ask the right questions: what are they waiting for, what are they rebuilding, and what would make the safe way the easy way? 🛤️🏛️🎓

⏭️ Next

The other schools. The CI/CD school goes deeper on pipelines; the Argo CD school on GitOps delivery and ApplicationSets; the Kubernetes school on what most platforms run on; the Observability school on the alerts and dashboards kits; the Security school on what the guardrails protect; the School portal has the rest.

git checkout main
python3 idp/demo.py     # one last run, for fun

← Previousmeasuring Finished! Take the quiz →check what stuck

This page is the lesson's README from the lesson-12-developer-portal branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.