doc(pos-doc): refactored README
This commit is contained in:
Stephan Lo
parent
13bd4343d9
commit
8d17325bcd
5 changed files with 113 additions and 93 deletions
81
README.md
81
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)
|
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.
|
||||||
- [📋 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)
|
|
||||||
|
|
||||||
---
|
## 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).
|
1. The platform orchestrator, processing declarative 'platform stack' descriptions
|
||||||
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.
|
1. The predefined stack for a Demo EDP instance
|
||||||
One usecase to demonstrate the capabilities of our tool is the PetClinic Application. (LINK)
|
1. The documentation
|
||||||
|
|
||||||
### 🛠️ Application Stack
|
### Platform Orchestrator `edpbuilder`
|
||||||
|
|
||||||
- **Version-Control:** Forgejo
|
[edpbuilder](https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW/edpbuilder) is a tool to quickly instantiate and manage Internal Development Platforms (IDPs).
|
||||||
- **CI:** Forgejo Actions
|
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.
|
||||||
- **CD:** ArgoCD
|
|
||||||
- **Monitoring:** Grafana, Prometheus, Loki, Promtail
|
|
||||||
- **SSO:** Keycloak
|
|
||||||
- **Developer Portal:** Backstage
|
|
||||||
- **Secret-Management:** OpenBao, external-secrets
|
|
||||||
- **Infrastructur-Provisioning:** Crossplane
|
|
||||||
|
|
||||||
## 📖 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: <https://edf-cc1.cx.fg1.ffm.osc.live/docs/edppoc/component/edp-documentation>
|
The `Demo EDP` Stack contains the follwing application components:
|
||||||
- Username: user1
|
|
||||||
- Password: PpMpfZYICG9MRRF-3QBY2Zz1-+URYB6+-JRe
|
|
||||||
|
|
||||||
### 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.
|
One usecase to demonstrate the capabilities and development lifecycle flow through all stack components is the [PetClinic Application](./docs/user-documentation/petclinic.md)
|
||||||
*[How to set up a local IDP on a kind cluster](docs/userguide/edpbuilder.md)*
|
|
||||||
|
|
||||||
### In the Forgejo repository
|
### Documentation
|
||||||
|
|
||||||
If you prefer direct access, the content of our documentation is centrally defined and maintained within the docs folder of this repository.
|
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 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)
|
||||||
[LICENSE]
|
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)
|
||||||
|
|
|
||||||
70
docs/introduction/index.md
Normal file
70
docs/introduction/index.md
Normal file
|
|
@ -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
|
||||||
|
|
@ -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
|
|
||||||
|
|
||||||
|
|
@ -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
|
|
||||||
14
mkdocs.yaml
14
mkdocs.yaml
|
|
@ -3,9 +3,7 @@ site_description: 'EDP documentation'
|
||||||
|
|
||||||
nav:
|
nav:
|
||||||
- Home: index.md
|
- Home: index.md
|
||||||
- Introduction:
|
- Contents: introduction/index.md
|
||||||
- User Documentation: introduction/user-documentation.md
|
|
||||||
- Technical Documentation: introduction/technical-documentation.md
|
|
||||||
- User Documentation:
|
- User Documentation:
|
||||||
- ArgoCD: user-documentation/argocd.md
|
- ArgoCD: user-documentation/argocd.md
|
||||||
- Backstage: user-documentation/backstage.md
|
- Backstage: user-documentation/backstage.md
|
||||||
|
|
@ -19,8 +17,8 @@ nav:
|
||||||
- PetClinic: user-documentation/petclinic.md
|
- PetClinic: user-documentation/petclinic.md
|
||||||
- Technical Documentation:
|
- Technical Documentation:
|
||||||
- Concepts:
|
- Concepts:
|
||||||
- Code: technical-documentation/concepts/1_software-and-workloads/_index.md
|
# - Code: technical-documentation/concepts/1_software-and-workloads/_index.md
|
||||||
- Engineers: technical-documentation/concepts/2_engineering-people/_index.md
|
# - Engineers: technical-documentation/concepts/2_engineering-people/_index.md
|
||||||
- Use Cases: technical-documentation/concepts/3_use-cases/_index.md
|
- Use Cases: technical-documentation/concepts/3_use-cases/_index.md
|
||||||
- Platforms:
|
- Platforms:
|
||||||
- Platform Engineering: technical-documentation/concepts/4_digital-platforms/platform-engineering/_index.md
|
- 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
|
- References: technical-documentation/concepts/4_digital-platforms/platform-components/references/_index.md
|
||||||
- Orchestrators:
|
- Orchestrators:
|
||||||
- CNOE: technical-documentation/concepts/5_platforms/CNOE/_index.md
|
- 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:
|
- Solution:
|
||||||
- Design: technical-documentation/solution/design/_index.md
|
# - Design: technical-documentation/solution/design/_index.md
|
||||||
- Scenarios: technical-documentation/solution/scenarios/_index.md
|
# - Scenarios: technical-documentation/solution/scenarios/_index.md
|
||||||
- Tools:
|
- Tools:
|
||||||
- Backstage:
|
- Backstage:
|
||||||
- Description: technical-documentation/solution/tools/Backstage/general-information/_index.md
|
- Description: technical-documentation/solution/tools/Backstage/general-information/_index.md
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue