diff --git a/README.md b/README.md index 20a66a6..b7275a5 100644 --- a/README.md +++ b/README.md @@ -1,65 +1,58 @@ -# 🌟 EdgeDeveloperPlatform - EDP Release 'PoC' +# 🌟 EDP - EdgeDeveloperPlatform -Telekom MMS & T-Systems, December 2024 +> * Owner: Telekom MMS & T-Systems +> * Date: December 20, 2024 +> * Version: Release 1.0.0 ('PoC') -> **Tagline:** Change the way we work with IDP's. +## About this Repository ---- +This repo [`edp-doc`](https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW-CICD/edp-doc) is the documentation repository of the **EDP product**. -## 📋 Table of Contents +## About the EDP Product -- [🌟 EdgeDeveloperPlatform - EDP Release 'PoC'](#-edgedeveloperplatform---edp-release-poc) - - [📋 Table of Contents](#-table-of-contents) - - [📖 About the Product](#-about-the-product) - - [🛠️ Application Stack](#️-application-stack) - - [📖 Access our Documentation](#-access-our-documentation) - - [In our Open Sovereign Cloud](#in-our-open-sovereign-cloud) - - [In a local kind cluster](#in-a-local-kind-cluster) - - [In the Forgejo repository](#in-the-forgejo-repository) - - [📝 License](#-license) +EDP is a product developed by the IPCEI-CIS subproject 'edge Developer Framework'. The goal is to provide a cutting edge developer experience for developing and delivering applications in the cloud edge continuum. ---- +## What EDP contains -## 📖 About the Product +The EDP product consists of three parts: -**edpbuilder** is a tool to quickly instantiate and manage **I**nternal **D**evelopment **P**latform's (**IDP**s). -The **E**dge **D**evelopment **P**latform Builder(**edp**builder) can easily setup a Kubenetes cluster (local kind cluster or OSC instance) and deploy tools to manage the Kubernetes resources and the software lifecicle of an application. -One usecase to demonstrate the capabilities of our tool is the PetClinic Application. (LINK) +1. The platform orchestrator, processing declarative 'platform stack' descriptions +1. The predefined stack for a Demo EDP instance +1. The documentation -### 🛠️ Application Stack +### Platform Orchestrator `edpbuilder` -- **Version-Control:** Forgejo -- **CI:** Forgejo Actions -- **CD:** ArgoCD -- **Monitoring:** Grafana, Prometheus, Loki, Promtail -- **SSO:** Keycloak -- **Developer Portal:** Backstage -- **Secret-Management:** OpenBao, external-secrets -- **Infrastructur-Provisioning:** Crossplane +[edpbuilder](https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW/edpbuilder) is a tool to quickly instantiate and manage Internal Development Platforms (IDPs). +The Edge Development Platform Builder (edpbuilder) can easily setup a Kubenetes cluster (local kind cluster or OSC instance) and deploy tools to manage the Kubernetes resources and the software lifecicle of an application. -## 📖 Access our Documentation +### Predefined `Demo EDP` Stack -Our documentation is designed to be easily accessible regardless of your environment. Here are three primary ways to view it: +There are predefined stack sets for deploying and orchestrating a whole platform. -### In our Open Sovereign Cloud +At the time of writing (version PoC) we provide the [`Demo EDP`as PoC stack](https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW-CICD/stacks). -Our documentation can be easily accessed through a Backstage instance hosted on our Open Sovereign Cloud (OSC). Simply log in to our OSC Backstage platform to read through the documentation. +#### `Demo EDP` Stack -- URL: -- Username: user1 -- Password: PpMpfZYICG9MRRF-3QBY2Zz1-+URYB6+-JRe +The `Demo EDP` Stack contains the follwing application components: -### In a local kind cluster +* Version-Control: Forgejo +* CI: Forgejo Actions +* CD: ArgoCD +* Monitoring: Grafana, Prometheus, Loki, Promtail +* SSO: Keycloak +* Developer Portal: Backstage +* Secret-Management: OpenBao, external-secrets +* Infrastructur-Provisioning: Crossplane -Using the edpbuilder, you can set up a local IDP that comes with a Backstage instance containing the documentation. -*[How to set up a local IDP on a kind cluster](docs/userguide/edpbuilder.md)* +One usecase to demonstrate the capabilities and development lifecycle flow through all stack components is the [PetClinic Application](./docs/user-documentation/petclinic.md) -### In the Forgejo repository - -If you prefer direct access, the content of our documentation is centrally defined and maintained within the docs folder of this repository. +### Documentation ---- +The EDP documentation is subject to this repo in folder [`docs`](./docs/). It is created in the [`mkdocs`](https://www.mkdocs.org/) documentation format and natively embedded in the [`Backstage TechDocs` documentation technology](https://backstage.io/docs/features/techdocs/). -## 📝 License +Thus it can be read in four ways by -[LICENSE] +1. [accessing the Backstage portal in a running Demo EDP](./docs/introduction/index.md#doc-in-backstage-in-a-running-demo-edp) +2. [accessing the Backstage portal in a Demo EDP setup on your computer](./docs/introduction/index.md#doc-in-backstage-in-a-demo-edp-setup-on-your-computer) +3. [browsing the documentaion repository](./docs/introduction/index.md#doc-in-the-repository) +4. [browsing in a Backstage simulation on your computer](./docs/introduction/index.md#doc-in-a-backstage-simulation) diff --git a/docs/introduction/index.md b/docs/introduction/index.md new file mode 100644 index 0000000..dbd1975 --- /dev/null +++ b/docs/introduction/index.md @@ -0,0 +1,70 @@ +# EDP Documentation + +## How to access the Documentation + +The EDP documentation is subject to this repo in folder [`docs`](./docs/). It is created in the [`mkdocs`](https://www.mkdocs.org/) documentation format and natively embedded in the [`Backstage TechDocs` documentation technology](https://backstage.io/docs/features/techdocs/). + +Thus it can be read in four ways: + +### Doc in Backstage in a running Demo EDP + +The documentation can be easily accessed through a Demo EDP instance hosted on our Open Sovereign Cloud (OSC). + +Thus there you have a Backstage-Developer Portal running, containing the EDP documentation. + +Simply log in to [Demo EDP Backstage](https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW-CICD/stacks) to read through the documentation. + +* [EDP Documentation URL](https://edf-cc1.cx.fg1.ffm.osc.live/docs/edppoc/component/edp-documentation) +* Username: user1 +* Password: PpMpfZYICG9MRRF-3QBY2Zz1-+URYB6+-JRe + +### Doc in Backstage in a Demo EDP setup on your computer + +As `edpbuilder` is a infrastructure agnostic platform orchestrator, you also can boostrap the EDP Demo on your own laptop! + +Using the edpbuilder, you can set up a local Demo EDP that comes with a Backstage instance containing the documentation: +[How to set up a local IDP on a kind cluster](./docs/user-documentation/edpbuilder.md) + +### Doc in the repository + +If you prefer direct access, the content of our documentation is centrally defined and maintained within the [docs folder of this repository](./docs/). + +### Doc in a Backstage simulation + +The Backstage TechDocs embedding can also be [emulated in a Backstage portal frame running on your computer](./live-preview-integration/README-backstage-local.md). + +## User Documentation + +### 📋 Outline +- [What is it? (short description what the software does, max 3 sentences)](#what-is-it) + - A couple of use cases (different scopes) + - Why do I need / want this? When should I pass? + - Compare with other platforms + - Compare with well-known tools (what parts of my stack / pipeline does this cover?) + - argo -> vercel + - monitoring -> data dog + - forgejo -> graphite +- [Main features (brief list of main features and enablers - why it is in the stack)](#main-features) + - what are our opinions / core principles and believes that are backed in? + - k8s > * + - Developer Portal: Backstage +- [Quick start guide](#quick-start-guide) +- [Configuration](#configuration) + - structure of the poc (where / how can I change something?) + - how does it work? (bootstrapping++) +- [Known Issues / TODOs](#known-issues) +- [References (documentation links etc...)](#references) + +### 🧐 What is it? + +10:40 THU + +### 📦 Main features + +### ⏱️ Quick start guide + +### ⚙️ Configuration + +### 🔗 References + +## Technical Documentation diff --git a/docs/introduction/technical-documentation.md b/docs/introduction/technical-documentation.md deleted file mode 100644 index 910f6e2..0000000 --- a/docs/introduction/technical-documentation.md +++ /dev/null @@ -1,7 +0,0 @@ -# Technical Documentation - -## Outline - -1. Concepts - The underlying platforming concepts of the Edge Developer Framework (EDF) solution, i.e. the problem domain - diff --git a/docs/introduction/user-documentation.md b/docs/introduction/user-documentation.md deleted file mode 100644 index c779ca9..0000000 --- a/docs/introduction/user-documentation.md +++ /dev/null @@ -1,34 +0,0 @@ -# User Documentation - -## 📋 Outline -- [What is it? (short description what the software does, max 3 sentences)](#what-is-it) - - A couple of use cases (different scopes) - - Why do I need / want this? When should I pass? - - Compare with other platforms - - Compare with well-known tools (what parts of my stack / pipeline does this cover?) - - argo -> vercel - - monitoring -> data dog - - forgejo -> graphite -- [Main features (brief list of main features and enablers - why it is in the stack)](#main-features) - - what are our opinions / core principles and believes that are backed in? - - k8s > * - - Developer Portal: Backstage -- [Quick start guide](#quick-start-guide) -- [Configuration](#configuration) - - structure of the poc (where / how can I change something?) - - how does it work? (bootstrapping++) -- [Known Issues / TODOs](#known-issues) -- [References (documentation links etc...)](#references) - -## 🧐 What is it? - -10:40 THU - -## 📦 Main features - -## ⏱️ Quick start guide - -## ⚙️ Configuration - -## 🔗 References -- Technical Documentation diff --git a/mkdocs.yaml b/mkdocs.yaml index 99cc540..e809f98 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -3,9 +3,7 @@ site_description: 'EDP documentation' nav: - Home: index.md - - Introduction: - - User Documentation: introduction/user-documentation.md - - Technical Documentation: introduction/technical-documentation.md + - Contents: introduction/index.md - User Documentation: - ArgoCD: user-documentation/argocd.md - Backstage: user-documentation/backstage.md @@ -19,8 +17,8 @@ nav: - PetClinic: user-documentation/petclinic.md - Technical Documentation: - Concepts: - - Code: technical-documentation/concepts/1_software-and-workloads/_index.md - - Engineers: technical-documentation/concepts/2_engineering-people/_index.md + # - Code: technical-documentation/concepts/1_software-and-workloads/_index.md + # - Engineers: technical-documentation/concepts/2_engineering-people/_index.md - Use Cases: technical-documentation/concepts/3_use-cases/_index.md - Platforms: - Platform Engineering: technical-documentation/concepts/4_digital-platforms/platform-engineering/_index.md @@ -32,10 +30,10 @@ nav: - References: technical-documentation/concepts/4_digital-platforms/platform-components/references/_index.md - Orchestrators: - CNOE: technical-documentation/concepts/5_platforms/CNOE/_index.md - - Humanitec: technical-documentation/concepts/5_platforms/Humanitec/_index.md + # - Humanitec: technical-documentation/concepts/5_platforms/Humanitec/_index.md - Solution: - - Design: technical-documentation/solution/design/_index.md - - Scenarios: technical-documentation/solution/scenarios/_index.md + # - Design: technical-documentation/solution/design/_index.md + # - Scenarios: technical-documentation/solution/scenarios/_index.md - Tools: - Backstage: - Description: technical-documentation/solution/tools/Backstage/general-information/_index.md